AMIGA
WORLD
ECH JOURNAL
ARTICLES
V 2 ARexx Arcana:
Hosts and QU0t6S ByManmWemstein
Successful command passing
37 Inside SCSI ByCregSerlm
An explanation of the spec
V 25 The Basics of Ray Tracing syi
Master light rays and shadows
V 3s An Introduction to Boopsi synmMackraz
The Amiga's own OOP
42 System Events and Vl/rlte your own ray tracer; see page 25.
Event-Handling Routines BynugemMortimore
A look at the Exec's bookkeeping
V 49 PostScript Primer syjimrmrc
Graphics-output starter kit
56 Get Noticed By Brian Sarraiin
Prime PR pointers
59 Start-up Messages By David Manm
Decode those flashing colors
REVIEWS
Y 34 RXTOOlS By Eric Gigitere
Intuition help for ARexx
36 AmeegaVieW ByDamdT.McaeUa>i
Shortcuts for C
60 Ml NIX 1 .5 By Stephen R. Pktrowkz
Mini-Unix for the Amiga
09
COLUMNS
1 Message Port
Learn or lend a hand
<^ 8 Digging Deep in the OS syjohnFoust
Choose your math hbrary
V 14 Graphics Handler syPauiMiUer
Easier gadgets from GadTools
31 TNT
Products just out and on the way
64 Letters
What are you really thinking?
'7447Q"12070'
U.S.A. $15.95
Canada $19.95
I Volume lyNomber 3
(See page 33)
2.0 include files: straight from
the CATS' mouth
Post: a PostScript interpreter
Plus source code and executables for articles
Au;
st/Septeinber 1991
An IPG Commamcations Ptibucatioi
Ca/Jtain's Log 217:2055
^ Time shift equalization mittines recoc/ed in
Aztec C. All systems go. It's good to be back borne.
ISH^^ceTlcem.^
Aztec
MS DS«
80x8
c:all Today for
Special Discount Prices
and Technical Information
space Simon 2055 - Viido Pollkarpus
Aztec C Is available for Amiga, Macintosh, MS-DOS, Apple II,
TRS-80, and CPM/80. Native and cross development.
Aztec Embedded C hosts on MS-DOS and Macintosh. Targets
include: 68000 family, S086 famUy, 8080/Z80/64180, & 6502
Aztec C includes - C compiler, assembler, linker, librarian,
editor, source debugger, and other development tools.
MANX^800-221-0440
• Outside USA: 908-542-2121 FAX: 908-542-8386 • Visa, MC, Am Ex, C.O.D,
domestic & international wire • one and two day delivery available
Manx Software Systems • 160 Avenue of the Commons • Box 55 • Shrewsbury l^J 07702
Linda Bairett Laflamme, Editor
Louis R. Wallace, Tecbnicat Advisor
Barbara Gefverl, Beth Jala, Peg LePage, Copy Editors
Rhett Andeison
Gary Bonham
Gene Brawn
Brad Carvey
Joanne Dow
Keith Doyle
Andy Finkle
Peer Revieto Board
John Foust
Jim Goodnow
Scott Hood
David Joiner
Sheldon Leemon
Dale Luck
R.J. Mical
Eugene Mortlmore
Bryce Nesbitt
Carolyn Scheppner
Leo Schtvab
Tony Scolt
Mike Sir\z
Richard Stockton
Steve Tibbett John Toebes Dan Weiss
Maie-Aiuie Jarvela, Manager, Disk Projects
Laura Johnson, Designer
Atana Korda, Production Supervisor
Debra A. Davies, Typographer
Kenneth Blakeman, National Advertising Sales Manager
Barbara Hoy, Sales Representative
Michael McGoldrick, Sales Representative
Giorgio Saluti, Associate Publisher, West Coast Sales
242] Broadwaii, Suite 200. Redwood City, CA 94063
ilS/363-5230
Heather Guinard, Sales Representative, Partial Pages
800/441-4403, 603/924-0100
Meredith Bickford, Advertising Coordinator
Wendie Haines Marro, Marketing Director
Laura Livingston, Marketing Coordinator
Margol L. Swanson, Customer Service Representative,
Advertising Assistant
Lisa LaFIeur, Business and Operations Manager
Mary McCoIe, Video Sales Representative
Susan M. Hanshaw, Circulation Director, SOO/365-1364
Pam Wilder, Circulation Manager
Lynn Lagasse, Manufacturing Manager
♦
Roger Murphy, President
Bonnie Welsh-Carroll, Director of Corporate Cirailation & Planning
Linda Ruth, Single Copi/ Sales Director
Debbie Walsh, Newsstand Promotion Manager
William M. Boyer, Director of Credit Sales £f Collections
*
Stephen C. Robbins, Vice-President/Group Publisher
Douglas Barney, Editorial Director
77ii" Ami^iiWortJ Tech Jnunittl (ISSN 1054-4631) is an indopedont journal no( cimnected
with CommodorL" Business Machines, Inc. The Amii;aWarld Tab limrtml is published bi-
monthly by IDG Ciimmunications/Pelerbofough. Inc., SO Elm St., Peterborough, NH
03458. U.S. Subscription rate is S69.95, Canada and Mexico S79.95, Foreign Surface
589.95, Foreign Airmail SI G9.95. All prices are for one year. Prepayment is ruciuired in
US. funds drawn on a U.S. baiik. Application to mail at 2iid class postage rates is pend-
ing al Peterborough, NH and additional mailing offices. Phone; 603-924-0100. Entire
contents aipyrighl 1991 by IDC Communications/ Peterborough, Inc. No part of this
publicdlion may be printi^ or othcr^^'iso reproduced ivilhout written pernii'isioii from
the publisher. Postmaster S*'nd address changes to TTic Ajili^aW['Tttt Trt/l lounuil, 80 Elm
St., Peterboiough, NH 03453. 7"lic Amiga World Tfch loiimal makes every effort to assure
the accuracy of articles, listings and circuits published in the magazine. Tire Ami^n VJorU
Tech jpunitit assumes no responsibility tor damages due to errors or omissiot^. Third
dass mail enclosed.
Bulk Rate
US Postage Paid
IDG CoiTtmunicatiorts/Peterborough, Inc.
MESSAGE PORT
We're all teachers.
I'M PLEASED THAT so many of you want to share your
expertise with fellow readers. Since vve started our confer-
ence on BIX (aw. tech journal, stop by), one of the most com-
mon questions I see is "How can I write for the Tech ]ouma\l"
The best way to start is to have a concrete idea and to
draw up a rough outline of the article. Mail the outline
along to me either by traditional means or via BIX
(llaflamme) and include the article's projected length, a list
of accompanying diagrams or listings, and a writing sam-
ple. Be sure to mention your credentials and background in
the cover letter. If we like the idea, I'll call and request the
complete article and code.
Remember, the Tech Journal's charter is to provide arti-
cles and listings that teach-the reader how to better use the
Amiga's unique capabilities. The stress is on Amiga; an
introductory language piece will never make it beyond the
"Thank you, but no thank you" bin. Past issues of the Tech
journal, CATS' AmigaMail, and DevCon notes are good
sources of inspiration.
Don't get so busy writing, however, that you can't take
time out for the 1991 North American Developers Confer-
ence. Slated for September 4-7 at Colorado's Denver Mar-
riott City Center, this year's conference should have a hill-to-
bursting schedule of technical seminars, considering all the
new hardware, 2.0, and CDTV developments. As tJiey were
last year, marketing and public relations sessions are also on
the agenda. Registered developers should receive registration
forms and information automatically. If you haven't, contact
CATS, 1200 Wilson Dr., West Chester, PA 19380.
While CATS is educating the developers, the Amiga
Developers' Association is rallying to educate the rest of the
computing world about the Amiga's strengths. Under the
leadership of a new board, the ADA is focusing on a single
goal: to promote the Amiga to all that will listen. The first
target is the computer press. As ammunition, the board will
use position papers on the Amiga's benefits for users and
developers. (Any potential authors out there?) The ADA
also wants to pass along profiles of companies and individ-
uals using the Amiga for innovative applications and
unique situations. (If you are, promote yourself. Contact the
ADA.) To offer your help, contact Chairperson Al Hospers
al Dr. T's Music Software, 220 Boylston St. #306, Boston,
MA 02167, If you'd like more general information or a
membership application (dues are S150 per year), write to
Treasurer Jerry Woiosenko, ADA Membership Drive, Psyg-
nosis, 29 St. Mary's Court, Brookline, MA 02146.
Whether educating programmers and engineers about
the latest techniques and teclinologies or educating the
world at large about the Amiga's power, we're all working
for the same goal: to advance and expand the the Amiga
market. Get in the game and help. ■
oLk ffB ijkrryr^^J^
The AW Tech Journal I
ARexx Arcana:
Hosts and Quotes
By Marvin Weinslein
EVERYONE AGREES AREXX (which is based on IBM's
REXX> lets you harness the power of multitasking by relaying
instructions between programs. A cloud of mystery and con-
fusion, however, hovers over the concept of an ARexx host
program. The number of ARexx-capable applications that can
serve as ARexx hosts is large and growing rapidly. As a result,
understanding ho\\' ARexx processes a command and passes
it to a host is vital. The key to this is understanding ARexx's
syntax and the way in which ARexx handles quotes.
SYNTAX OVERVIEW
Because a REXX command is defined in terms of what it is
not, a lightning review of REXX syntax is in order. The sim-
plest meaningful statement that can appear in a REXX pro-
gram is a clause. The ARexx interpreter recognizes six types
of clauses:
A Comment
A statement enclosed between a /* and its matching */,
which is usually ignored by REXX. Every REXX program,
however, must begin with a comment. (On IBM mainframes
the comment was used to distinguish REXX programs from
scripts written in IBM's EXEC language.)
An Instruction
A statement that begins with one of 32 keywords. The 32
instructions, combined with assignment statements, define
the skeleton of all REXX programs. They determine the man-
ner and order in which things happen. For example, the SAY
instruction causes ARexx to type a line of text to the CLI that
launched the ARexx exec (program).
/* beginning comment 7
say hello
produces:
HELLO
A Label
A clause that consists of a single name followed by a colon,
such as:
START:
You use labels to indicate the beginning of subroutines or.
in special circumstances, to modify the flow of control in a
REXX program.
An Assignment
Any clause of the form:
name = expression
where a variable name is followed by an = and an expression
to be evaluated.
A Null
A blank line or a line containing only a semicolon.
A Command
Any clause that does not fall into one of the preceding cat-
egories. When ARexx encounters a command clause it eval-
uates the expression and then passes the result to an exter-
nal host for further action. The externa! host may be either
the native operating system or an application program de-
signed to receive and act upon ARexx messages. You can
modify the default host for an ARexx program using the
ADDRESS instruction. A large portion of problems come
from misunderstanding who the default host for a program
is, and what limitations that host operates under. (More on
this later.)
The fact that REXX is typeless makes it easy to learn. No
need to specify variables in advance; as far as REXX is con-
cerned all variables are strings and defined, whether or not
they have appeared on the left side of an assignment state-
ment. If a variable has not been assigned a value, by default
REXX assigns it the string obtained by uppercasing the vari-
able's name. For example, it is REXX's job to figure out if the
variable r in the statement:
X = 4*r
has a value for which the * operation is well defined. If r has
not appeared in an assignment statement, REXX uppercases
the r to obtain:
X = 4*R
and recognizes that it does not kno^v how to multiply a num-
ber by a letter. The program then fails and produces an error
message.
Because the REXX interpreter treats all strings that do not
contain blanks as possible variables, it automatically upper-
cases text as it goes along. To tell ARexx not to examine a
string for possible substitutions, we enclose it in matching
single or double quotes. Thus, the program:
2 AiipisijSeptembn 1991
Avoid misquoting commands and the host trouble that follows
hy learning some of ARexx's more esoteric facets.
/"rexx:sayltrexx
say Hello world
say "Hello world"
say 'Hello world'
say "Hello" world
produces the output:
HELLO WORLD
Hello world
Hello world
Hello WORLD
Because you can use either single and double quotes, it is
easy to include a quote inside a text string. For exarnple:
/" rexx:quotetest.rexx
say "Ttils Is an example of a string with a quota ' "
say 'This is ar example of a string with a quote " '
produces the output:
This Is an exaniple of a string with quote '
This Is an example of a string with a quote "
Another mechanism for including a quote in a string is to
type either " or "". In this case REXX eats the first quote and
prints the second. For example:
/"* rexxiescapetest.rexx
say 'This is an example of a string with a quote " '
say "This Is an example of a string with a quote "$kern4pt" "
produces the same output as the quotetest.rexx example.
This simple discussion illustrates why quoting is used and
the need for adopting a flexible set of quoting conventions.
As long as you limit yourself to manipulating strings within
ARexx programs, there is nothing more to know. Peculiari-
ties arise, however, when you send strings containing quotes
to an ARexx host. You must understand how ARexx pro-
cesses a command line and the quoting conventions required
by the host application to avoid problems caused when host
applications use the same quoting characters as ARexx.
COMMANDS AND HOSTS
To guarantee that ARexx will immediately recognize a line
as a command clause, you enclose it in quotes. In fact, the IBM
REXX manual recommends this as good programming style.
As an alternative, you could begin the line with a pair of
matched quotes. For example, if an ARexx exec contains the
following:
""dtr
"dir"
dir
ARexx instantly recognizes the first two lines as commands,
but treats the third differently. First ARexx checks to see if dir
is a built-in instruction. Because this test fails, ARexx next
looks in the rexx: directory for a file named dir.rexx or dir.
Not finding one, it passes dir to the default host to see if the
host knows what to do with the command.
Who is the default host for the program and will it know
how to field this command? Things are starting to get com-
plicated. The default host for an ARexx program depends
upon how the ARexx program was launched. Even for pro-
grams launched from a shell, there is a difference between
those programs launched using rx and programs launched
without using rx, from a truly ARexx-integrated shell.
As ARexx arrived after the original Amiga CLI was devel-
oped, it is not as well integrated into the CLI environment as
REXX is on an IBM mainframe running VM/CMS. One triv-
ial, but annoying, aspect of this lack of integration is that un-
der AmigalX)S 1.3 you cannot launch an ARexx program by
typing only its name. To run an ARexx program called
myprog.rexx from a CLI (or Shell) you must type:
rx myprog
Under Amiga DOS 2.0 the situation is better, but not great.
If you set the script bit for an ARexx program and add the
file's directory to your path, you can execute the program by
typing only the full name of the file, including the .rexx ex-
tension. This is a minor annoyance,
A more serious complication is that under both AmigaDOS
1.3 and AmigaDOS 2.0 the script is actually launched using
rx. The only difference is that in one case the rx is explicit.
While being able to omit the rx command is cosmetically
nicer, in both cases the default host for the process is not the
underlying CLI (or Shell) but REXX. As proof, run the fol-
lowing program;
/** rexx:addresstest.rexx
'•/
say "Hi, my address Is"
sayaddressO *
The A W Tech Journal 3
ARexx Hosts
using rx addresstest. Because REXX is the default host, you
encounter some unexpected problems. For example, wliat
happens if you run the program:
/"rexximydir.rexx
*
"dir"
by t3rping:
rx mydlr
The correct answer is nothing. In interpreting the program,
ARexx recognizes the single command clause and passes it
to the default host, which is REXX itself. The second time
REXX gets the command without quotes, because it ate one
level of quotes when it interpreted the string. REXX now at-
tempts to resolve dir as an instruction, and so on. To avoid
an infinite loop, it will no longer pass the command to itself,
therefore failing to resolve the command. The result is that
nothing happens.
The situation is quite different if you nm the same program
from a truly ARexx integrated shell, such as the WShell re-
placement shell marketed by William Hawes, the creator of
ARexx. WShell knows about ARexx.
When you type something such as my-
command, WShell automatically searches
the rexx: directory for an ARexx program
with the name mycommand.rexx or my-
command. This makes launching ARexx
programs as simple as launching ordinary
executabtes. Second, if you run the pro-
gram addresstest.rexx from a WShell, the
output will be something like:
'•I
say addressO
address command 'dir >rain:dirllst'
say addressO
or, equivalently:
/" rexx:dlrtofile2.rexK
*
say addre3s( )
address command
'dlr>ram:dlrllst'
say addressO
(Note that the command clause must be in quotes in these ex-
amples or ARexx will attempt to interpret the line and break
on the : and the >.)
While it may appear that using the ADDRESS COM-
MAND instruction to run system commands is only slightly
more cumbersome than having a WShell as a default host, ap-
pearances are deceiving. Things get more complex when you
wish to launch a series of commands that must be executed
sequentially.
"A simple mechanism
for telling an ARexx
exec to execute a
WSH 1
which is different from what happens in
an Amiga Shell. This occurs because each
WShell has an ARexx port and can serve
as the default host for an ARexx program
launched from it. If you run the program
mydir.rexx from a WShell, ARexx recog-
nizes "dir" as a command clause, strips off the quotes and
passes dir to the default host, WSH 1, which treats dir as if
you entered it from the keyboard. This makes issuing system
commands much more transparent.
A simple mechanism for telling an ARexx exec to execute
a string as a system command is the ADDRESS instruction.
Use it to change the default host for dir to be AmigaDOS. You
may place the ADDRESS COMMAND instruction either in
front of the command clause to be executed by AmigaDOS
or on a separate line. When ADDRESS COMMAND appears
on the same line as the command clause, it changes the de-
fault host to COMMAND for only that clause; when the in-
struction appears on a separate line, then it changes the de-
fault host to COMMAND for all subsequent command
clauses. Both methods are illustrated below. Try running each
example from a CLI (or Shell) to see what happens. If you
have WShell, launch each of them with and without using rx.
No matter how these programs are launched, the command
dir >ram:dirlist executes correctly; only the results returned
by the ADDRESS function differ.
/" r»xx:dlrtofilel.rexx
string as a system
command is the
ADDRESS instruction.
SUBTLETIES WITH MULTIPLE
COMMANDS
Consider the problem of printing a
file with an ARexx exec using a pro-
gram that requires a stack size of 20000
when your default stack is 4000. If you
run it from a WShell, the following
program will work:
/*' rexx:texprlnt.rexx
"/
arg fitename
"stack 20000"
"dvllj -o par: work:dvlflles/"ftlename",dvi"
exlto
In this case the command clauses are
sequentially issued to the same host, say WSH_1. If, howev-
er, you modify the program to:
f" rexx:texprlnt2.rexx
"/
arg filename
address command
"stack 20000"
"dvil| -o par: work:dvifiles/"flleriame".dvi"
exit
it will break because the stack will be too small for dvilj. Tlie
COMMAND keyword in the ADDRESS instruction tells
ARexx to execute each command as an independent process.
Thus, effectively, the command:
stack 20OOO
is executed in one Amiga shell, and the command:
dvllj -c par: work:dvlfltes/"(llename".dvl
is issued in another. This would appear to be a serious limi-
tation to running ARexx without WShell, but fortunately
4 AiigustlSepteinber 1991
ARexx Hosts
there is a simple solution. Create a single string of commands,
concatenating individual coininands separated by the line-
feed character "OA"x. As in:
string = "command 1"||"0a"x||command 2[|"0a"x||. . .
Now, send this one string to a shell using:
address command string
This trick is very useful for ARexx execs that cannot de-
pend upon the existence of WShell.
A more interesting problem is to open a CLI to show the
output of the dviljp command as it runs, and then close the
shell when finished. In this case, the previous approach needs
a somewhat arcane modification, as shown below for OS 2.0:
/" rexx:printlt.rexx
a
arg filename
siring = "stack 20000 +"||'Oa'x
string = strlngH"run dvllj -o par: "fllename".dvi +"
string = string||'Oa'x||"endcli"
runstring = "run > CDn:10/10/100/100/prlnting..^close "||string
address command runstrjng
exItO
A + is needed after each command be-
cause the Amiga DOS run >con:... con-
struction redirects the output of the com-
mand series to a CLI; thus, now the
multiple string command belongs to run
and AmigaDOS 2.0 rules apply. Without
the + characters, the stack 2000 command
would go to the newly opened CLI and
everything else would go to the shell that
launched the program.
address AmlgaTeX
redirect subsequent commands to the indicated message ports.
Be sure to note that ARexx does not interpret the string that
immediately follows the ADDRESS instruction. If the string is
enclosed in quotes, ARexx uses it as is; otherwise ARexx auto-
matically converts it to uppercase. Because ARexx conducts a
case-sensitive search for public message ports, you must pro-
vide quotes whenever needed or the search will fail. ARexx
does interpret the expression that follows the port name.
A common mistake with the ADDRESS instruction is to try
something clever, such as:
/' program-specific code here '/
myprogram = "Pro Vector"
/' more code here */
address myprogram command
This trick fails to accomplish the desired result because
ARexx attempts to pass the command to a port called MY-
PROGRAiM, instead of Pro Vector. The VALUE keyword tells
ARexx to interpret the symbol or string that follows, before
constructing a port name. Hence:
address value myprogram
causes all subsequent commands to be forwarded to the port
ProVector. Given the way in which the ARexx par-
ser works, however, the instruction:
ADDRESS CHANGES
ARexx-capable applications have one
or more public message ports to which you can send ARexx.
When ARexx programs are launched from ■within an appli-
cation, the default host is customarily set to be one of these
ports. If the program needs to interact with more than one ap-
plication, then you must repeatedly change the default host.
To do so, you use one of the ADDRESS instruction's four
general forms:
ADDRESS Istrlnglsymbol) expression
ADDRESS {siringlsymbol)
ADDRESS VALUE expression
ADDRESS
You are already familiar with a special case of the first two
forms from the previous examples that used ADDRESS
COMMAND, either by itself or on the same line as the com-
mand clause. While ADDRESS can take either COMMAND
or VALUE as a keyword, all other strings that immediately
follow the ADDRESS instruction are interpreted as the name
of a public message port. Thus:
address TURB0TEXT7
address 'TxEd Plusi
address 'ProVector'
address FASTHOST
"The names of
all ARexx ports
should be all
uppercase."
ADDRESS VALUE expressions
cannot be followed by a command clause
on the same Une. After ADDRESS VAL-
UE is used, the default host for the pro-
gram is changed. To make restoring the
original default host simple, ARexx
keeps both the new host and the previ-
ous host in memory. Using the AD-
DRESS instruction by itself toggles be-
tween these two values. Therefore;
address command
r program-speciiic code here */
n = 7
myprogram = ■'TURBOTEXT"n
address value myprogram
/' more code tiere '/
address
say address( )
produces the output
COMMAND
Actually, you can use a trick to accomplish the same thing
as the VALUE keyword without changing the default host.
Use the INTERPRET instruction. A construction such as:
interpret address myprogram command
will work just as well.
The Amiga style guidelines recommend that the naimes of
ARexx ports should be all uppercase, which makes a lot of
sense. First, it avoids the need for quoting the string that fol-
lows the ADDRESS instruction, which is a common source
of problems with ARexx programs. Second, when you write
complicated programs that launch string execs containing an
ADDRESS instruction, every extra required quote hurts.
The A W Tech journal 5
ARexx Hosts
(Note: The fact that the true name of a public message port
is all uppercase does not prevent you from enhancing read-
ability by typing names in mixed case. ARexx automatically
converts the name to uppercase before sending any mes-
sages, unless forced not to.)
Unfortunately, not all current applications conform to the
style guide's recommendations. For this reason you must
know the correct name of a message port to send it a message.
Its name should be in the application's manual. K not, you can
run the program and then type:
n "say showllst('p')"
to view a list of all pubhc message ports-
FLEXIBLE QUOTING NEEDED
A final class of quoting problems arises when you try to in-
clude ARexx string programs inside command clauses. As an
example, consider one of the earliest ARexx-capable Amiga
applications, the editor TxEd Plus. TxEd Plus lets you add or
delete menu items that are capable of launching ARexx ex-
ecs. The syntax of the command used for this purpose is:
MENU n K "Menu Text" ARexx_program
where n is a menu number from to 5, K is a letter specify-
ing the keyboard alternative for the menu
item, the text that follows is what appears
in the menu, and ARexx^program speci-
fies the name of the program to be run. At
first glance this is not a bad syntax, but
problems arise because TxEd Plus requires
that quotes be used for its quoting charac-
ters.
Suppose that you wish to run an ARexx
exec to add new menu entries. In that case,
to add an entry to menu 5, with keyboard
alternative Z, which launches the exec
CalcStuff/calc.rexx, you have to type:
end. The example below will work:
MENU 5 B '"Begin numt>ered points"
""txedstuff/newllne""'"
"'INSERT ""\pointbegm"
"The notion
of a string program
IS unique
to ARexx."
While this sort of program looks considerably more myste-
rious than the preceding one, it is not difficult to understand.
Remember that ARexx first processes the line before handing
it on. This means that the outermost quotes in each string dis-
appear and, simultaneously, the double-double quotes are con-
verted to single<iouble quotes before the line is passed to TxEd
Plus. When TxEd Plus receives it the line looks like:
MENU 5 B "Begin numbered points"'lNSERT "\polntbegin";"txedstuff/
newline"'
Examine the file startup.txed for more examples.
This sort of programming would be much simpler if a more
flexible way of handling the quoting problem had been
adopted by the host application. One way to increase flexi-
bility would be for the host to allow additional quoting char-
acters, as well as a way to handle program strings that con-
tain more than one line, as indicated by the presence of
semicolons. An example of a program that handles this sort
of scripting in a more general manner is provided by the ter-
minal program VLT. Another way to overcome this kind of
difficulty is to include keywords for the
host to parse on instead of using quotes.
An example of this sort of approach is tak-
en in the editor program called TurboText.
Obviously, many strategies can be adopt-
ed to handle the proliferation of quotes
that appear when people try to stuff string
programs into command clauses; the com-
mon feature of all solutions is that the host
application has to be more flexible in its
quoting than ARexx.
MENU 5 Z '"Launch Calc CalcStuff/calc.rexx"
Why do you need two sets of quotes enclosing Launch
Calc? ARexx will eat the first set of quotes when it processes
the line, and TxEd Plus requires the string that follows to be
enclosed in double quotes if it contains spaces. Even the or-
der of the quotes used in this example is forced upon you; if
you type '"Launch Calc'" you will not obtain the desired out-
come. The program name must also be enclosed in quotes so
that ARexx does not attempt to do a division before passing
the result to TxEd Plus, Because the quotes are eaten by
ARexx, TxEd Plus receives a valid program name to pass to
REXX whenever the new menu item is selected.
While this example is not too bad, consider what happens
if you replace the name of an ARexx program with a string
program. A string program is an ARexx invention that allows
you to execute short ARexx execs directly by typing:
rx "llnel ; Ilne2 ; ... "
where the semicolons are REXX's end-of-line character. Either
single or double quotes are acceptable as delimiters for a
string program. String programs let you avoid having a large
number of small ARexx files associated with an exec that cre-
ates multiple menu entries. Because an enclosing set of quotes
must survive after ARexx has eaten the outermost quotes in
the example, you must use all of your tricks to achieve that
FINAL ADVICE
ARexx has abilities that transcend those
possessed by REXX on any other platform. With these pow-
ers, however, comes added complexity. Understanding how
comnnand clauses get passed to a host apphcation is impera-
tive. The ADDRESS instruction includes a mechanism for
sending ARexx messages to public message ports, but you
must remember that port names are case sensitive and that you
need the VALUE keyword to use a computed string in the
ADDRESS instruction. Finally, the notion of a string program
is unique to ARexx. While this is a very powerful facility, ex-
ploiting it can lead to bizarrely complicated quoting patterns.
The key to working out these complexities is to keep in mind:
• ARexx eats one level of quoting each time it processes a Une.
• ARexx converts escaped quotes (double-double or double-
single quotes) to ordinary quotes each time it processes a line.
• You must also know how the host application handles the
processed line when it receives it.
If in a given project you find it difficult to sort out quoting
complexity, then making liberal use of the tracing console and
ARexx's built-in tracing commands can provide you with
valuable insights into what is happening. ■
Marvin Weiustein uses ARexx and REKX extensively in his
work at the Stanford Linear Accelerator, Write to him cjo The
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH
03458, or contact him on BIX (mweinstein).
6 AugustlSeptember 1991
This is the most cost effective way to
increase the speed of your computer.
AdSpeed™ I
AdSpeed
ICD expands its line of innovative enhancement products for the Amiga with the
introduction of AdSpeed, a low cost, full featured 14.3 megahertz accelerator for
all 68000-based Amiga computers.
A.dSpeed differs from other accelerators by using an intelligent 16K static RAM
cache to allow zero wait state execution of many operations at twice the regular
speed. All programs will show improvement. No 68000 or 68020 accelerator
without on board RAM will make an Amiga run faster.
AdSpeed continues ICD's tradition of providing the best product available.
These are .some of the features that set it apart from the rest:
• Works with all 68000-based Amiga computers, including the 500, 1000, and
2000.
• Simple no solder installation — just remove the computer's 68000 and plug
AdSpeed into its socket.
• Low power, high speed CMOS 68000 CPU for full 100% instruction set com-
patibility.
• Software selectable speeds, with a true 7.16 megahertz mode for 100% com-
patibility. Switches speeds on the fly without rebooting the computer.
• 32 kilobytes of high speed static RAM — 1 6K of data/instruction cache and
16K of cache tag memory.
• Full read and write-through cache for greatest speed.
• Bus monitoring to prevent DMA conflicts.
• ICD's famous quality, dependability, and support.
• Worlds smallest 68000 accelerator. (Photo above is actual size).
ICD, Incorporated 1220 Rock Street Rockford, IL61101 USA
(815) 968-2228 Information (800) 373-7700 Orders (815) 968-6888 FAX
AdSpeed h a trademark of ICD, Inc. Amiga is □ regiiilercd rrodemark oif Comnx>do re- Amiga, Inc.
DIGGING DEEP IN THE OS
/\ Floating-Point
\t Math Alternatives
By John Fous!
CHOOSING THE WRONG floating-point math model for
your C program could cut performance in half, double or
triple memory consumption, or introduce numeric error in
calculations. It might even prevent your program from run-
ning on some Amigas. Balancing these trade-offs and pick-
ing the best model requires an understanding of AmigaDOS's
floating-point math libraries, how a C compiler translates
floating-point operations to assembly language, and how a
compiler's link libraries perform math operations.
First, take a look at what your choices are. Several of the
system libraries contain functions that perform math opera-
tions with IEEE (Institute of Electrical and Electronic Engi-
neers) and FFP (Fast floating-point) floating-point numbers.
Table 1 lists the system math libraries and the type of func-
tions they contain. The base math libraries perform simple
operations (addition, multiplication, negation, and so on),
while the transcendental libraries contain functions such as
sine and cosine, plus functions to translate numbers between
IEEE and FFP formats. (For a complete list of math library
functions see the Amiga ROM Kernel Reference Manual: In-
cludes & Autodocs, Addison- Wesley.)
The Motorola fast floating-point system stores floating-
point numbers in 32 bits. The IEEE 754 standard includes
both single-precision values in 32 bits and double-precision
values in 64 bits. Motorola's 68881 and 68882 numeric co-
processor chips use the IEEE format. Table 2 shows each rep-
resentation's minimum and maximum values for numbers
(using C's version of scientific notation), the digits of preci-
sion (relevant number of digits after the decimal point), along
with the storage size.
The Motorola coprocessors and the Amiga OS double-pre-
cision IEEE libraries use double-extended numbers for their
intermediate calculations. These numbers use 80 bits of stor-
age. Both SAS and Manx C store these types in 96 bits (12
bytes) of data storage. Tliey could be stored in just ten bytes,
but storing them in three 32-bit longs is faster and more con-
venient, especially on the 68020.
OLD STYLE OR STANDARD
What's the difference between FFP and IEEE? FFP math is
quite fast, even though the calculations are done in software.
It does not offer double precision, however, or speed up if a
coprocessor is available. The IEEE format offers both single
and double precision for more freedom and control over
floating-point calculation and storage. If your programs are
going to exchange binary data with other types of comput-
ers, IEEE is a good choice. Although, IEEE is about twice as
slow as FFP, it will perform as fast or faster than FFP if a co-
8 AtigustjSeptember 1991
processor is present.
Your C compiler adds another level of complexity to your
choice. In Standard C programs, there are three possible float-
ing-point data types: float, double, and long double. Standard
C allows a compiler to represent the float, double, and long
double types in the same way. (It recommends a floating-
point representation with a range similar to single-precision
IEEE, meaning that the FFP model is not quite good enough
for Standard C.) Having both floats and doubles represented
by single-precision values is perfecfly legal under the FFP
models and is supported in Manx and SAS C. Even under
IEEE math models, SAS C has compiler switches to set the rep-
resentation of float and double types. With these, you can rep-
resent all floating-point types as either single- or double-pre-
cision, or split-single and double types as different precisions.
In an expression that combines floating-point variables
with built-in operators such as +, -, *, and /, the compiler eval-
uates the expression in a predictable way, to generate as-
sembly language and data to represent the floating-point val-
ues. In evaluating the expression, a conversion between types
can take place: integers can be converted to floats, floats to
doubles, and so on, before the rest of the expression is eval-
uated. Promotion from one type to another is defined to
progress from int to float to double to long double. For ex-
ample, in an expression involving an int and a double (and
no other type casts), the integers are promoted to doubles,
and the entire expression is performed in double precision.
When calling a function with floating-point arguments,
similar promotion can take place. In old-style C, all floating-
point arithmetic was defined to take place in double preci-
sion. In a function call, all float parameters were promoted
to double, then pushed on the stack. Under Standard C, a
function's prototype determines if floats will be promoted to
double before being pushed on the stack. In the absence of a
function prototype, promotion takes place as in old-style C.
If a Standard C function prototype says the argument is a
float, it stays a float.
Take a look at the theory in action. Listing 1 shows a very
short C function that loads a constant into a double, multi-
plies that double by two, then takes the cosine of it and stores
it into a long double. In math.h, the cosO function is declared
as accepting a double and returning a double. Listing 2
shows the assembly language generated for this function,
as compiled for FFP math and generated by the Manx 5.0
compiler. Listing 3 shows the IEEE version. Listing 4 shows
it under double-extended IEEE, and Listing 5 shows it with
direct in-line 68881 codes.
Examine these listings side by side and you will quickly see
the difference in the code generated under each math mod-
el. In the FFP listing, no distinction is made between float,
double, and long double. Simple 32-bit values are loaded
into registers, and such internal subroutines as jsr .fmul# are-
called to perform math. In the IEEE and double-IEEE list
Listing 1: Original (unclion()
#lnclude <math.h>
functlonO
{
float a;
double b;
long double c;
b = 3.14159;
a = b • 2;
Table 1
Amiga library
Contents
mathffp.llbrary
FFP math functions
mathtrans.library
FFP transcendental functions
mathieeesingbas.llbrary
IEEE math operator library,
uses coprocessor if present
mathleeesingtrans.llbrary
IEEE transcendental library,
uses coprocessor if present
mathieeedoubbas.llbrary
IEEE double precision library,
uses coprocessor If present
mathieeedoublrans.library
IEEE double transcendentais,
uses coprocessor if present
Table 2
Type
Minimum
Maximum
Digits of
Precision
Size
in bits
FFP
5.4e-20
9.2e19
6-7
32
32
Single IEEE
1.3e-38
3.4e3S
6-7
Double IEEE
2,2e-308
1. 86307
15-16
64
Double Extended IEEE
3.4e4932
1.2e4932
19
80(96)
c s cos(a};
Listing 2: FFP
; #include <math.h>
I
; functlonO
;{
xdef _funetion
Junction:
link a5,#.2
movem.l .3,-(sp)
; floats;
; double b;
; long double c;
;b = 3.14159;
move.i #$c90fd042,-12(a5)
; a = b ' 2;
moveJ -12(85)40
move.i #$80000042,di
Jsr .Fmul#
move.1 d0.-4(a5)
;c = cos(a);
cir.l -{sp)
move.i -4(a5),-{sp)
jsr _cos
add.w #8,sp
move.i dO,-20(a5)
;}
.4
movem.l (sp)+,.3
unik as
rts
.2 equ -20
.3 feg
xref _cos
xref .begin
(taeg
end
Listing 3: IEEE
; #include <mstti.h>
; functlonO
:(
xdef Junction
Junction:
link a5,#.2
movem.l .3,-(sp)
; float a;
; double b;
; long double c;
; b = 3.14159;
move.i #$f01b8eel,-8{a5)
move.l j!»$400921f9,-12(a5)
;asb*2;
move.i -8(a5),d1
move.i -I2(a5),d0
move.) #$00000000,d3
move.i #$40000000,d2
Jsr .Pmui«
Jsr .dtof#
move.i d0,-4(a5)
1
; c = cos(a);
move.i •4(aS),dO
Jsr .ftod*
move.i dl,-(sp)
move.i dO,-(sp)
Jsr _co3
add.w ^,sp
move.i dl,-l6(a5)
move.l d0,-20{a5)
;1
.4
movem.t (sp)+,.3
unIk a5
rts
.2 equ -20
.3 reg d2/d3
xref _cos
xref .begin
dseg
end
The AW Tech jounial 9
Digging Deep in the OS
Listing 4: Double-Extended IEEE
#{nclude <:math.h>
tuncUonO
{
xdef _func11on
_tunction:
link a5,#.2
movem.i .3,-(sp)
float a;
double b;
long double c;
b = 3.14159;
move.l #$f01b866f,-8(aS)
move.1 #$400921 f9,-l2(a5)
;a = b*2;
move.) •8(a5),d1
move.1 -12(a5),d0
move.) #SOO00OOOO,d3
move.! #$40000000,d2
jsr .Pmultf
jsr .dto1#
move.l d0,-4(a5)
; c = cos(a);
move.l -4{a5),d0
Jar .ftod#
move.l d1,-(sp)
move.l dO,-(sp)
jsr _cos
add.w #8,8p
|sr .dtox#
L inove.1
.pO+3,-16<aS)
move.l
.pO+4,-20(a5)
move.
.pO,-24{aS)
:}
.4
movem.i (sp)+,.3
unik
aS
rts
2 equ
-24
.3 regd2/d3
xref
i
pO
xref
_C08
xref
begin
dseg
end
Listing 5: Direct 68601
^include <math.h>
functlonO
{
xdef Junction
Junction:
link a5,«.2
movem.l .3,-{sp)
fmovem.x .4,-(sp)
floats;
double b;
long double c;
; b = 3.14159;
.5
move.l «$f01b866f,-8(a5)
fmovem.x (sp)+,.4
move.l #$400921 f9,-l2(aS)
movem.l (sp)+,.3
unIk as
; a = b * 2;
rts
Iinove.d-12(a5),fp0
.2 equ -24
fmul.d #"$4000000000000000
■,fp0
.3 reg
fmove.s fp0,-4{a5)
.4 freg
; c = cos(a);
fmove.s •4(a5),fp0
xref .begin
fcos.x fpO
dseg
fmove.x fp0,-24(a5)
end
;)
ings, the double constants are twice as large as the FFP con-
stants. Storing doubles in memory or on disk consumes twice
the memory or disk space as using single precision. In the c=
cos(a) line of the double-IEEE listing, note that it takes three
long-word move.l instructions to store the long-double quan-
tity. The direct 68881 listing is very different than the others.
In it the compiler generates special 68881 coprocessor in-
structions (such as fmul.d and fcos.x fpO) instead of calling
internal subroutines to perform the math. The limitation is
you need a 68020 or 68030 CPU, plus a coprocessor chip to
run the program.
COPROCESSOR COOPERATION
The 68020 and 68030 support direct, tight-coupled access
to the numeric coprocessor chip. The 68000 supports only a
slower interface, treating the 68881 coprocessor as a periph-
eral device. At one time Microbotics and CMI provided a re-
placement ma thieeedoubbas. library that called their periph-
eral 68881s, allowing 68000-based Amigas to use the 68881 as
a peripheral. Although these devices could double the speed
of math operations, they never became commonplace. Un-
fortunately, few commercial applications used the IEEE dou-
ble-precision library. As the Amiga market matured, math-
intensive programs were usually offered in two forms: an
integer- or FFP-based version that worked quickly on any
Amiga and a version compiled for the Amigas equipped with
a 68020 and 68882. Since Amiga OS 1.3, however, the double-
precision libraries can take advantage of numeric coproces-
sor chips, as long as they declare a math resource during the
autoconfig process. This means both 68000/68881 and
68020/68882 combinations give faster results, if present.
In Amiga OS 2.0, Commodore added a new math-
ieeesingbas. library that has the same functions as the
matliffp.library, except that it uses a math resource if present.
This library gives the speed of single-precision IEEE with the
added benefit of using a coprocessor, if present. Under Ami-
ga OS 2.0, the system will not auto-init the library, so it is not
on the library list until an application asks for it. Under very
low memory the library init could fail, therefore do not as-
sume success. Check the result of the OpenLibraryO call be-
fore continuing.
LIBRARY LINGO
After the compiler turns the assembly language interme-
diate file to an object file, the linker comes into play. Do not
be confused by the word "library." It has two contexts in a
math models discussion: A given compiler has link libraries,
and the Amiga OS has math libraries. An OS library is es-
sentially a program that contains useful subroutines that any
other program can call — the mathteeedoubbas.library in the
LIBS: directory is an example. A compiler's link libraries are
composed of object .o modules that contain definitions of •
30 August/September 1991
RXTools
RXTools is an object oriented interface builder which extends the capabilities
of ARexx and the Amiga. With the built in editor, RXTools provides a complete
development system for ARexx on the Amiga.
ARexx function host environment system which runs in the background - ARexx Required.
Allows you to create windows, gadgets, requesters and more within your ARexx applications.
Provides a programming addition to ARexx not otherwise available.
Built in editor allows easy manipulation of RXTools and ARexx scripts.
AmigaDOS VI. 3 and 2.0 Compatible.
Retail Price $54.95
MRBackup
Professional
mmMm
dr«ii *
■■«.., T^. *,T1I
Kfiir
a—
' •'^'IllCTII
8^
-.-iPsrs-rm
Ittt
n^
17^
'israsnun
im
m
S^Bf 1
MRBackup Professional allows for easy yet powerful backup
commands at the click of a gadget. MRBackup Professional will allow
backups to floppy, another hard drive, virtual file, SCSI streaming tape, or even to DAT tape.
• SCSI Streaming Tape Capability - Use your existing controUer and a SCSI tape drive, NO Extra hardware
required (most controllers and SCSI drives supported). • Utilizes full compression. (12 to 16 bit), to save
backup space. - With FastDisk option, even floppy backups take less time. • Has full ARexx integration. -
Allows for complete external control of the backup options." AmigaDOS VI. 3 V2.0 Compatible.
Retail Price $54.95. With Tanberg 150Mb SCSI Streaming Tape External $949.95 Internal $749.95.
Wangtek 150Mb SCSI Streaming Tape External $999.95 Internal 799.95,
Sony ftill height DAT External $2049.95 Internal $1849.95.
i gMnq;^
V^:'
Sapphire Accelerator
68020 / 68881
Fits snugly In an Amiga 1000, 500, and 2000
For easy installation, included is a disk with instnactions, pictures and some public
domain benchmark software. Also included is an electrostatic discharge (ESD)
information card, and an ESD safety strap. Features include:
• Factory Installed 12 MHz 68020 CPU And 68881 FPU 32 Bit Processors operating at 7.16 MHz.
• Speed Increases Of Up To 2.4 Times Faster In Integer, And 3.2 Times Faster
In Floating Point.
• SraaU Compact Size, Smallest Yet At Only 3 1/8" x 4 1/4" x 1/2".
• Not A Pseudo Accelerator, but a true 32 Bit Accelerator Card
Using 32 Bit Processors.
• One Full Year Factory Warranty,
• Retail Price 399.95
TTR Development, Inc
6701 Seybold Rd. Suite 220
Madison, WI 53719
Dealer Pricing Available!
Sales And Technical Support
608-277-8071
BBS Support 608-277-8072
■wmaiiHiiLmmninmnnBiwinmi
INNOVATIVE SOFTWARE FOR
THE COMPUTER INSIDE US ALL
Bix support under TTR. Support
»IUIIII I .»]M.ll l Ul l tlll« l ill l ll llll lMll ll imiM„ I H I HMail lilll! limilllJI II I I
Digging Deep in the OS
such C library functions as fopenO. Other link libraries —
one for each math model — contain subroutines that perform
arithmetic operations on floating-point numbers. When you
link your program's object modules, the final executable is a
mixture of the functions that you wrote plus functions from
the standard link libraries. If your program performs float-
ing-point math, you must link with the proper library to per-
form those math operations.
To complicate things, a compiler's math link library can in-
voke functions in an OS library. An example is SAS C's
icmieee.lib link library. It opens the Amiga's IEEE library to
perform math. (Also, note that both IVlanx and SAS C offer
IEEE link libraries that do not open the system's libraries, but
instead link in a stand-alone IEEE math implementation.)
By linking with the proper math link library, internal sub-
routines such as the jsr .fmul# are resolved. Listing 6 shows
the source code for the interna! subroutine .Fmul. It simply
calls the SPMuK ) function in the Amiga's ITP library, inside
the amiga_ffp# internal subroutine, which first checks to
make sure that library is open and ready.
Listing 6: Direct 68881
; Copyright (C) 1986 by Manx Software Systems, Inc.
;:t9s8
public .Fmul]
.Fmul:
CrossDOS
...MS-DOS
i: DISK ACCESS
HI DONERIGKT!
" Version 4
Suggested Retail:
The first MS-DOS File System for the ylMJG/1-
• Rcidi Of wntei my 360K or 720K WS-DOS Of ATARI ST* disks
(Version 2.0 or higher) y-itJi slandard Anjiga-conrtectcd floppy inva.
• Trarttparenily accoso MS-DOS files from any utililj or applicaiioFt
(includtng nie requesien) because it fiilly inicgraics itiio The Amiga
irpcfiumg: syiwn. (Ampj-^^OS Vcnionii 1.2, 1.3 and Z0>.
• provide! in tas> inHallaiion pTOEram.
#RifTnil,distcopyafw! eh«k lhcintc|nl> of an MS-IXlSdiik
Break the 720K Barrier . . .
• Access many megabyics ofdats tiiing ^isnd^ (crcusvablc canridfes
and enicm^l haid dnwes. {MakfABamlJUnkJilcs NOTiupptifieJ)
• Using >™^ Ami^a hard drive conlrotter. vou can access mosi MS-
DOS formaitcd hard dnve media jusT lifct MS-IXIS floppies.
Bvfning and weekend BBS available for upd.iic infor-
lion and lo traile uploads or PD file convtrsiun p;n)inim\
13 1 J) 4^9-7271 --SPM to 10 AM EffTun wcckdiyi
II d:iy i>[l weekends.
Reviewed !n many
popular Amiga
Magazines:
'ki^^'kic Raiing
'Cn'uSmStt truly
exreUtrti it S g wonder
fhai nn/tne lha'j/;ht ofthii
iKiintifr/ui lilro dK^i anti. '
DivkJ W, Mantfl,
.info Magazine
"... CmssDOS li unquei-
rionuhty rhe hesi uriliry I
fiave jftitfiirrmdiniifinm
and wrtiing so i.S-inch
MS-DOS ^iski on the
Tim \Viljh
Aniiy-iWorlil
" , nmv i ir/idfila back
and/nrth la antifinm IBM
tufidin a tiHalh Ifuniptir-
rnJ fashiiin'
Jim l-octcr
Amiiinj Computing
inalitir
BBS*
Lind al
C0NSUl7if?0iV
11230 Pajkviavv
P^ymoul^. Mr -13170
I313ui59-7271
move.! #_LVOSPMul#,-(sp)
]mp amlga_fi|>tf
One common mistake is to list the link libraries in the
wTong order when telling the linker how to produce an exe-
cutable. The symptom is that floating-point numbers do not
print from the printfO hinction. For example, in Manx C's
IEEE model, you need to specify the ma.lib before the c.lib.
Each math Hnk library contains a variant of the printfO func-
tion that understands the math model. Be careful, the Stan-
dard C link library has a version of printf( ) that does not un-
derstand the %f format specifier. If the linker sees the c.lib
printfO before the math library printfO, it links the wrong
function into your executable.
THE CHOICE IS YOURS
This might seem obvious, but if your program does not
perform any floating-point operations, then you do not need
to link it with a math library. What defines a math operation?
Any part of an expression involving a floating-point type, or
a cast to a floating-point type, invokes internal math func-
tions. For example, even though a program has no floating-
point variables, an expression in the program might cast in-
teger variables to floats to perform an accurate division by a
fractional number.
As you can see in the assembly language listings, it is pos-
sible to initialize floating-point variables without linking with
a math library, as long as you do not use any Standard C op
erators with these variables. If you open a math library on
your own and call the SPMulO function yourself, there is no
overhead of jumping through the compiler's stubs and in-
ternal subroutines.
If }'ou want raw speed, consider integer math. If your ap-
plication can avoid floating-point and perform fixed-point in-
teger arithmetic, chances are it will be faster than any float-
ing-point implementation.
If you do need to use a Hbrary, the FFP libraries are about
twice as fast as 1.3 IEEE libraries and give a reasonable
amount of precision for most applications. OS 2.0's math-
ieeesingbas.library, however, complicates your choice. One of
the main advantages of the FFP library was that it was in
ROM and thus available on every Amiga. Because the library
was also relatively fast for nonhardware-assisted math, it
was the correct choice. With the arrival of high-end applica-
tons that need more accuracy and speed coupled with in-
dustry pressure for a standard floating-point format, CATS
staffers recommend the mathieeesingbas.library which is
built in ROM, almost as fast as the mathffp.Iibrary on non-
coprocessor machines, and much faster on coprocessor-
equipped Amigas.
If you prefer accuracy, standardization, and the added bene-
fit of running much faster on enhanced machines, choose the
IEEE libraries or consider direct 68881 instructions for the
fastest possible math on enhanced Amigas. Also, tliere is no rea-
son not to turn on your compiler's 68020 code generation, be-
cause all 68881 -equipped Amigas ha ve an advanced processor.
As with al! program design choices, the "best" math mod-
el involves decisions about speed and storage. Keep your
preferences and the above tips in mind, and the trade-offs be-
tween math models will be more apparent. ■
John Foust is president of Syndesis Corp. Contact him c/o The
Amiga World Tech Journal, 80 Elm St., Peterborough, NH 03458.
12 Aii};usllScptember 1991
Means Color!
atasdg...
Our Only Business Is Color.
If you've produced a quality
color imaging product...
You can choose no better
publistier than ASDG.
CALL US AT (608) 273 - 6585
GRAPHICS HANDLER
\^ The GadTools Library
By Paul Mifter
WORKBENCH 2.0'S PROFESSIONAL look and opera-
tional consistency are attributable primarily to the new gad-
get constructs available in the GadTools library. An integral
part of this latest operating system, GadTools combines the
look of 2.0 and aspects of several standard controls to form a
set of new gadget classes. These gadgets can make your life
much easier, and that's why GadTools is not just a tool — it is
an interface programmer's friend!
The best thing about GadTools is its ease of use. GadTools
lets you create an entire list of complicated gadgets with
much less effort and hassle than you are used to. With one
function and a few parameters, for example, you can create
an entire scrollable list gadget, complete with slider and ar-
row buttons — GadTools automatically combines the neces-
sary controls into a single gadget. No longer must you cre-
ate a proportional gadget and combine it with two Boolean
gadgets to make a scroller — simply ask for a Scroller Gad-
Tools gadget, and the system takes care of the busy work and
maintenance for you!
GadTools is also extremely extensible. This means that as
new gadget classes and parameters become available, you
can easily add them using 2.0's tag facility. Tags are a means
of providing information to many nevv 2.0 functions without
filling out such large temporary structures as NewScreen and
NewWindow. They also allow the easy addition of new fea-
tures. If you omit tags, the system typically defaults to a
group of standard settings. For that reason, you need set only
the specific parameters you require.
Tags are specified either as an array of Tagltems or as vari-
able parameters — containing the tag and its data — to the
function. Here is the format of the Tagltem structure:
typedel ULONG Tag;
struct Tagllem {
Tag tl_Tag; /' lag ID '/
ULONG ti_Data;
I;
Tagltem lists are terminated with a tag of type TAG_DONE
or TAG_END.
TAG— YOU'RE A GADGET!
In version 36 of gadtools.librar)', there are 13 kinds of gad-
gets. Each type has a set of tags that specify required or spe-
cial information about the gadget.
Both the GENER1C_K1ND (a standard gadget type) and
BUTTON_KIND (an action button) accept the disable tag.
34 August /September 1991
This also applies to most other gadget types:
QA_DISABLED (BOOL; delault = FALSE)
Set to TRUE lo disable ttie gadget, FALSE otherwise.
The CHECKBOX_KIND is a state-selecting gadget. A
checkmark appears when the gadget is activated. You can use
the check tag with it:
GTCB_Checked (BOOL; delauH = FALSE)
The Initial state of the checkbox {TRUE = CHECKED).
The CYCLE^KIND is a single button with multiple states.
This gadget q'cles forward through a list of strings each time
you click on it. It also cycles backward through the list when you
hold down the Shift key and click. Its corresponding tags are:
GTC¥_Labels (STRPTR •)
A required tag, this Is a NULL-termlnated array of string pointers.
These strings comprise the gadget's offerings.
GTC¥_Active (UWORD; delault = 0)
The ordinal number (counting from zero) of the initially active
choice in the cycle.
INTEGER_KIND is a standard string-editing gadget that
allows you to edit only integers. The Integer gadget accepts
these tags;
GTIN„Number (ULONG; default = 0)
Determines the initial contents of the integer gadget.
GTIN_MaxChars (UWORD; default = 10)
The maximum number of digits that the Integer gadget can hold.
A powerful gadget, LISTVIEW KIND displays a list of
items that you can select and scroll through. It has an optional
scroll bar with arrows and an optional editing facility for the
selected item. ListView accepts several tags:
GTLV_Top (UWORD; default = 0)
Determines the top item (ordinal) visible In the llsl.
GTLV Labels (struct List •)
A required tag, this acts as a pointer to an Exec List of lat>els
whose ln_Mame fields are displayed In the list.
GTLV Readonly (BOOL; default = FALSE)
If TRUE, LIstVlew is a read-only gadget.
GTLV_ScroliWidlh (UWORD; default = 16)
Determines the width of the scroll bar.
GTLV ShowSelected (struct gadget *)
Set to NULL to have the currently selected item displayed be-
neath the list. Alternately, set to a pointer to an existing GadTools
STRING_KIND gadget If you wrant an editable display of the
currently selected item.
'GadTools lets you create an entire list of complicated gadgets with
much less effort and hassle than you are used to."
GTLVSelected (UWORD; default = -0)
Ordinal number of the currently selected Item, or -0 (or no cur-
rent selection.
LA¥OUTA_SPACING (default = 0)
Extra space to place between lines of the list.
The MX KIND gadget provides a set of items that, like ra-
dio controls, you can select only one at a time. Its tags are:
GTMX_Labels (STRPTR ")
This tag is required. It serves as a l4ULL-termlnated array of
string pointers. These strings will appear as the latiels beside the
choices In the gadget.
GTMX_Actlve (UWORD; default = 0)
The ordinal number (counting from zero) of the initially active
choice in the gadget.
GTMX_Spaclng (UWORD; default = 1)
The amount of space between each choice of a set of mutually
exclusive gadgets. This amount, added to the font height, pro-
duces the vertical shift between choices.
NUMBER_KIND is a read-only display gadget for inte-
gers. To it you can add:
GTNM_Number (default = 0)
A signed long Integer to be displayed as a read-only number.
GTNM_Border (BOOL; default = FALSE)
II TRUE, this flag causes a recessed border to appear around the
gadget.
The PALETTE_KIND gadget contains a display of all the
available colors for the current screen, in addition to a box
containing the "current" color — that is, the color selected
from the gadget. The Palette gadget tags include:
GTPA_Depth (UWORD; default = 1)
Sets the number of bitplanes In the palette.
GTPAColor (UBYTE; default = 1 )
The palette color selected Initially.
GTPA_ColorOffset (UBYTE; default = 0)
Determines which color to use first In the palette.
GTPA JndlcatorWIdth (UWORD)
Determines the width of the current-color Indicator. Set this If you
want the indicator to appear above the palette.
GTPAJndicatorHeight (UWORD)
Determines the height of the current-color Indicator. Use this tag
If you want to place the Indicator to the left of the palette.
The SCROLLER_KIND gadget combines a proportional
slider and two optional arrow buttons. The result is a
ready-to-go scroller gadget that automatically tracks the
position and size of the slider control. You have your
choice of several tags for the Scroller gadget:
GTSC_Top (WORD; default = 0)
Determines what appears at the top of the area that the scroller
represents.
GTSC_Total (WORD; default = 0)
The total number of items In the scroller area,
GTSC_Vlslble (WORD; default = 2)
The numtier of things visible in the scroller.
GTSC_Arrows (UWORD)
Attaches arrows to the scroller. The value supplied serves as the
width of each arrow button for a horizontal scroller or the height
of each button for a vertical scroller (the other dimension match-
es the whole scroller).
PGA_FREEDOM (default = LORIENT_HOHIZ)
Determines whether the scroller Is horizontal or vertical. Choose
from LORIENT VERTor LORIENT HORIZ.
GAJMMEDIATE (BOOL; default = FALSE)
Set to TRUE if you want to be notified of every GADGETDOWN
event from the scroller.
GA_RELVERIFY (BOOL; default = FALSE)
Set to TRUE if you want to be notified of every QADQETUP event
from the scroller.
The SL1DER_KIND combines a proportional gadget and,
optionally, a numeric display that depicts the level or inten-
sity of some value. Corresponding tags are:
GTSL_Min (WORD; default = 0)
Sets the minimum level of the slider.
GTSL_Max (WORD; default = 15)
Maximum level of the slider.
GTSL_Level (WORD; default = 0)
Current level of the slider.
GTSL_Maj<LevelLen (UWORD)
Maximum length In characters of the level string when rendered
beside the slider.
GTSL^LevelFormat (STRPTR)
A C-style formatting string for the slider level. Be sure to use the I
(long) modifier. This string Is processed using the EXEC RawDo-
Fmt() function.
GTSL LevelPlace (default = PLACETEXT_LEFT)
Indicates where the level Indicator appears relative to the slider.
Settings are PLACETEXT_LEFT, PLACETEXT^RIGHT, PLACE-
TEXT_ABOVE, or PLACETEXT_BELOW. ■
The AW Tech lounmllS
Graphics Handler
GTSL_DlspFuiic ([LONGffuncHon)(struct gadget ', WORD)];
default = 0)
This function calculates the level to be displayed. For example, a
slider to select the number of colors might require a (1 « n)
function here. Your function must take a pointer to a gadget as
the first parameter, the level (a WORD) as the second, and return
the result as a LONG.
GA_IMMEDIATE (BOOL; default = FALSE)
Set to TRUE if you want to be notified of each slider GADGET-
DOWN event.
GA_RELVERIF¥ (BOOL; default = FALSE)
Set to TRUE If you want to be notified of each slider QADGETUP
event.
PGA_FREEDOM (default = LORIENT_HORIZ)
Set to LORIEMT_VEHT or LORIENT_HORIZ to create a vertical or
horizontal slider.
STR1NG_KIND is a standard alphanumeric string-editing
gadget. The tags it supports are:
GTST string (STRPTR; default = NULL)
Specifies the initial contents of the string gadget. Set It to NULL if
the beginning of the string Is to be empty.
GTST MaxChars (UWORD)
The maximum numt>er of characters that the string gadget Is to hold.
TEXT_KIND, the last type of gadget, is a read-only al-
phanumeric text display. For tags you can choose among:
GTTX_Te)rt (default = NULL)
Serves as a pointer to a NULL terminated string to be displayed
as a read-only text-display gadget or NULL.
GTTX_CopyText (BOOL; default = FALSE)
This flag Instructs the text-display gadget to copy the supplied
text string Instead of continuing to refer to the address of the
supplied string.
GTTX_Border (BOOL; default = FALSE)
If TRUE, this flag causes a recessed border to surround the gadget.
SET UP AND AWAY
Because GadTools resides in a ROM Ubrary, you must do
some initial setting up before you can actually create a gad-
get. GadTools also requires a pointer to a Visual Info block,
which you can get by accessing either the Workbench screen
or a custom screen. Finally, because Workbench 2.0 allows the
user to choose almost any font as the standard, GadTools is
very font-size specific and thus must know your font choice
so it can place gadget text properly. You will typically want
to force Topaz 80, so ask for it explicitly. See the setupO func-
tion in the demo program (in the Miller dravver of the ac-
companying disk) for the initialization described here.
Now you are ready to create a gadget list. Because all Gad-
Tools gadgets are dynamically allocated, GadTools provides
a simple way for linking, adding, refreshing, and freeing en-
tire lists of gadgets. To define your gadget list, declare a point-
er to a gadget structure and call the GadTools CreateCon-
textO function with the pointer's address:
struct gadget 'glist = NULL;
struct gadget 'gad;
gad = CreateContext(&gli5t);
This allocates a private gadget that describes the list. It also
forms a base to which you can add more gadgets, and on
which you can perform gadget-adding and -refreshing opera-
tions. Use the returned gadget pointer as a foundation for
building your gadget list with CreateGadgetO.
CreateGadgetO is the variable-arguments version of the
gadget-allocation function and takes the gadget type, a point-
er to the previous gadget, a pointer to a NewGadget struc-
ture, and the GadTools gadget tags as its parameters. The
physical description of the gadget is specified in the New-
Gadget structure:
stioicl NewGadget
(
WORD ng_LeftEdge, ngTopEdge; r upper-teft '/
WORD ng_^Width, ng_Height; /* size "/
UBYTE •ng_GadgetTeKt; r text label */
struct TextAttr •ng_TextAttr; /* label font V
UWORD ng_GadgetlD; /' gadget ID '/
ULONG ng Flags; /* special flags */
APTR ng_Vlsuallnto; r Visuallnio */
APTR ngUserData; T your data"/
1;
Now, you must assign the Visuallnfo pointer (obtained
earher) to the ng_VisuaIInfo field, and assign a declared Text-
Attr structure to the ng_TextAttr field. Then, finally, you are
ready to create a gadget.
Fill out a NewGadget structure with the position and size
of the gadget, a title, and an ID, along with the Font and
Visuallnfo information. To create a simple gadget of type
BUTTON_KIND, you simply pass the required informa-
tion:
gad = CreateGadget(BUTTON_KIN0, gad, &newgad, TAG_DONE);
For a more complex type, say a Scroller gadget, you might
want to add some more tags:
gad = CreateGadget(SCROLLER„KIND, gad, &newgad,
PGA_FREEDOM, LORIENT_VERT,
GTSC„Tota!, 20,
GTSC_Vlsibie, 10,
GTSC_Arrows, 16,
GA_RELVERIFY, TRUE,
TAG^DONE);
To allocate a complete list of gadgets, begin with the gad-
get pointer returned from your CreateContextO call. Make
the necessary adjustments to your NewGadget structure be-
tween calls to CreateGadgetO, and then pass the gadget
pointer returned from each call as the previous pointer in the
following call. You need not check for allocation problems
until the last gadget is requested, because CreateGadgetO
will simply return a NULL pointer if it receives NULL as the
previous gadget pointer.
Once you have your gadget list, you can add it to a win-
dow and refresh the imagery with the standard Intuition gad-
get functions. Then you must call GT RefreshWindow( ) on
the window, so special GadTools imagery can receive the
proper treatment. Additionally, new GT_BeginRefresh() and
GT_EndRefresh() functions are provided to replace the stan-
dard Intuition window-refreshing functions.
FURTHER EVENTS
GadTools can also make dealing vnth gadget events much
simpler. Using the new GT_GetIMsg() and GT_ReplyIMsgO
Continued on p. 61
16 Aii^iist/Scptcniber 1992
Inside SCSI
Your system probably uses this interface every day,
but do you know how it works?
By Greg Berlin
AS MORE COMPLEX tasks are required of microcom-
puters, system designers face the challenge of integrating
all the functions required of sometimes dissimilar compo-
nents, while maximizing system performance and mini-
mizing the cost and effort involved in putting the system
together. The current method of choice is the Small Com-
puter Systems Interface (SCSI, pronouned scuzzy). The
SCSI bus provides a standard means of connecting multi-
ple intelligent peripherals to a host computer (see Figure 1).
Thus, you can add many different types of devices (large
hard drives, tape drives, CD-ROMs, and so on) to the host
computer without modifying the generic system hardware
or software.
While almost everyone has heard of SCSI, even many vet-
eran computer users may not fully understand what SCSI is
all about. First of all, the term small in SCSI's name imphes
that its application is confined to microcomputers and that its
performance is limited. (Tlie pronunciation "scuzzy" has not
enhanced the standard's image, either.) As you will see, de-
spite these misnomers, SCSI is indeed a powerful interface
and well worth investigating thoroughly. It has found appli-
cations in machines spanning the entire spectrum of perfor-
mance and price.
SCSI CONCEPTS
A very basic, yet important point to understand is that the
SCSI bus is an I/O (input/output) bus, as opposed to a sys-
tem bus or a device-level interface bus. A system bus (such
as ZORRO II /HI, NuBus, STD BUS, IBM PC BUS, or MULTI-
BUS I/II) is generally the place to add expansion cards. De-
vice-level interface buses (including ST-506, ESDI, SMD, and
QIC-36) provide the means to take physical control of a de-
vice, via analog or digital signals, to manage such tasks as
head positioning and reading and writing raw data, Device-
level interfaces can be attached directly to the system bus. A
good example is the common ST-506/412 controller that
plugs into the IBM PC BUS. Usually up to two ST506/412-
compatible disk drives can be plugged into this controller
board. While this method minimizes immediate cost, it lim-
its expandability and versatility. If you want to add a tape
drive, for instance, you need to purchase another device-in-
terface controller card to support the tape-drive interface •
SCSI History
The SCSI interface's roots go back
as far as the early 1960s. IBM's popu-
lar mainframes at that time made
use of a byte-wide parallel I/O bus,
known as the block multiplexer chan-
nel, that was capable of block trans-
fers. Recognizing the need for an in-
terface standard, the ANSI X3T9.3
committee began to define one in the
early 1980s. Despite the popularity of
IBM's block multiplexer channel, the
ANSI committee decided not to ac-
cept it unchanged, due perhaps to the
NIH (not invented here) syndrome or
to political pressures from IBM's
competitors. The standard that ANSI
was developing was called the intel-
ligent peripheral interface (IPI). The
IPI bus was basically functionally
equivalent to the block multiplexer
channel, with a number of additions.
As an alternative to the block mul-
tiplexer channel of IBM, other groups
were working on developing their
own parallel I/O bus. Shugart Asso-
ciates developed the Shugart Associ-
ates System Interface (SASI). Shugart
was in the business of manufacturing
disk drives, and several other drive
manufacturers followed the compa-
ny's lead and adapted the SASI inter-
face to their drives. Because several
of the key drive manufacturers adopt-
ed this interface, it became relatively
widespread.
Shugart obviously had a great in-
terest in seeing their parallel interface
bus, instead of the IPI bus, adopted by
the ANSI X3T9.3 committee. When it
appeared that SASI would lose the
battle, Shugart renamed its bus inter-
face "SCSI" and submitted it to the
ANSI X3T9.2 committee, where the
competition was less entrenched.
(The ANSI X3T9.2 committee deals
with low-level interfaces.)
In 1984 the ANSI committee com-
pleted the SCSI-1 specification, and it
was published in its final form in 1986.
Further improvements and refine-
ments in the standard have resulted in
the recent release of the SCSI-2 speci-
fication, which is currently in its final
draft review (and may be published
by the time you read this). For a copy
of the SCSI-2 draft proposal (docu-
ment X3.1 31 -1 98X), contact Global En-
gineering Documents, 2805 McGaw,
Irvine, CA 92714, 800/854-7179.
—GB
TlicAWTechJourmll?
Inside SCSI
Figure 1: A Multiple-Host and Multiple-Peripheral SCSI System
Target Device
Initiator
CPU/RAM (:
HOST
ADAPTER
Inituior
CPU/RAM
->
/N
Syitem But
HOST
ADAPTER [\j-
SCSI BUS
Device Level
Inter&ce Bus
(such as QlC-36). Systems that require several disks or other
peripherals can benefit from the added SCSI bus I/O layer,
SCSI offers advantages in flexibility and system performance.
You can connect several different peripherals to a single SCSI
I/O bus, and the peripherals can communicate directly with
each other. Bus speed is certainly not a limiting factor, as
SCSI transfer rates have now reached up to 40 megabytes
per second (MB/sec).
The SCSI bus can support up to eight devices connected to
it. At first glance this may seem rather limiting, but the al-
lowance in the spec for eight logical units per device and 256
logical subunits per logical unit provides more than enough
expansion.
Each of the devices on the SCSI bus must be assigned a
unique ID number, which is usually set with jumpers on the
18 AugiistlScpiembcr 1991
device. The SCSI ID serves two purposes: It uniquely identi-
fies a device on the bus and it defines the device's priority
during bus arbitration (the higher the device number the
higher its priority).
Each of the eight possible devices is defined as an initiator,
a target, or both. An initiator is part of the SCSI host adapter
that connects a host computer system to the SCSI bus. In a
typical system, a single initiator connects with one or more
targets. A more complex system may have more than one
SCSI host adapter (multiple initiators). Tliis type of system
can not only establish communication from any processor to
any peripheral, but also from a host to host, because the host
adapter is itself a SCSI device and can be a target as well as
an initiator. Two peripherals (targets), however, cannot nor-
mally communicate with each other, and only two devices
Inside SCSI
(one initiator and one target) can communicate with each
other over the bus at any one time.
A host adapter consists of the hardware and software re-
quired to connect to the SCSI bus as an initiator, as well as
the hardware and software to interface this logic to the liost
CPU. With the proliferation of single-chip SCSI controllers
that can operate as both initiators and targets, constructing a
SCSI host adapter has become quite easy. Typically, these
single-chip devices attach directly to the SCSI bus on one
side and, with a minimum of logic, are adaptable to any sys-
tem bus on the other side, The SCSl-chip-to-system-bus in-
terface can be as simple as software-polled I/O or more com-
plex to enable high-speed data transfer via DMA. These
single-chip controllers accept high-level commands and re-
lieve the host CPU of the burden of manipulating and mon-
itoring the SCSI bus signals.
Host system software is simplified because it no longer
has to be concerned with the physical attributes of the device.
The SCSI interface uses logical rather than physical address-
ing for all data blocks.
SCSI BUS PHASES
The SCSI protocol uses eight distinct logical phases: BUS
FREE, ARBITRATION, SELECTION, RESELECTION, COM-
MAND, DATA, STATUS, and MESSAGE. The last four are
collectively known as the information transfer phases. The
SCSI bus can be in only one of the eight states at a time.
The BUS FREE phase signifies that no SCSI device is ac-
tively using the SCSI bus, and that the bus is available for use.
This phase is entered after a system reset or after the RST sig-
nal resets the bus. The BUS FREE phase is indicated by the
deassertion of the BSY and SEL signals.
The ARBITRATION phase is entered when a SCSI device
wishes to gain control of the bus as a master, This occurs
when an initiator wants to select a target or a target wants to
reselect its initiator. The ARBITRATION phase can be en-
tered only from the BUS FREE phase. After a device deter-
mines that the bus is free, ARBITRATION begins by assert-
ing the BSY signal and the SCSI ID of the device making the
request on the appropriate data bit. Each of the eight possi-
ble SCSI devices uses a single data hne to indicate its pres-
ence. The device with the highest ID number wins the arbi-
tration and gains control of the bus (data bit 7 has the highest
priority and bit the lowest).
The SELECTION phase allows an initiator to select a tar-
get for the purpose of initiating a target function, such as a
READ or WRITE command. In SCSI-2 the SELECTION phase
is always entered following an ARBITRATION phase. SCSI-
I supported a single initiator option that eliminated the need
for bus arbitration, so SELECTION could be entered follow-
ing a BUS FREE phase. In both cases, the target is selected
when the initiator puts the ID number of the target on the
data lines and asserts the SEL signal.
The optional RESELECTION phase occurs when a target
device wants to reconnect with the initiator that previously
sent it a command. This phase takes place basically the same
as the SELECTION phase, except the I/O line is asserted
along with the SEL signal so that it can be distinguished.
The COMMAND, DATA, STATUS, and MESSAGE phas-
es are grouped together as information-transfer phases be-
cause they are all used to transfer data or control information
via the data bus. The C/D, I/O, and MSG signals are used to
distinguish between the different information transfer phas-
es (see Figure 2). The target drives these signals and therefore
controls all changes from one phase to another. The REQ/
ACK (and REQB/ ACKB) lines are used to control the trans-
fer of data between the target and initiator during the infor-
mation-transfer phases.
The actual data transfer can be accomplished via syn-
chronous or asynchronous protocols. Both methods make
use of the ACK and REQ signal lines to perform the hand-
shaking. The synchronous transfer mode is optional for a tar-
get device. An initiator can request that a target perform syn-
chronous transfer, but if it is rejected then asynchronous
mode is used.
When data is to be transferred to the initiator in asyn-
chronous mode, the target drives the data Hnes and asserts
the REQ signal. Data is held until the ACK signal is received
from the initiator. The next data is then provided on the bus,
and the process is repeated. When transferring data in the op-
posite direction, the target asserts the REQ signal, indicating
that it is ready to receive data. The initiator drives the data
lines and then asserts the ACK signal. The initiator continues
to drive the same data until the REQ signal goes false. The
target then negates the REQ signal, the initiator provides new
data, and the process is repeated.
If the devices agree to the synchronous mode during the
message phase, the target device does not wait for the ACK
signal before sending the REQ signal for the next data. In-
stead, the target may generate one or more REQ pulses ivith-
out the corresponding ACK pulse received (up to a pre-
agreed maximum known as the REQ/ACK offset). Upon
generating all the REQ pulses, the target compares the num-
ber of REQs and ACKs to verify that each data set was suc-
cessfully received. To set up the synchronous data transfer,
the devices establish a REQ/ACK offset (the maximum al-
lowed number of REQs without corresponding ACKs re-
ceived during the transfer) and the transfer period, Tlie trans- •
Figure 2: Information-Transfer Phases
MSG
1
1
1
1
C/D
1
1
1
1
I/O
1
1
1
1
Phase Name
DATA OUT
DATA IN —
COMMAND
STATUS
(reserved for future use)
(reserved for future use)
MESSAGE OUT
MESSAGE IN
Description
Data sent from Initiator to target
Data sent from target to Initiator
Command sent from initiator to target
Status sent from target to initiator
Message from initiator to target
Message from target to Initiator
The AW Tech Journal 19
Inside SCSI
fer period determines the time between the end of one byte
of data transmission and the beginning of another. (Figure 3
illustrates bus phase flow,)
SCSI-2 ENHANCEMENTS
Although the original SCSI spec published in 1986 (SCSI-
1) was a great stride forward, it was lacking in some key ar-
eas. The SCSI-1 spec lacked sufficient definition to ensure
compatibility between devices. The spec made reference to
many different commands, but actually required the imple-
mentation of only a single one (REQUEST SENSE). The re-
sult was that different devices supported different com-
mands, limiting the number of controllers that could "plug
and play" in a particular SCSI system. Even as the SCSI-1 sp>ec
was being finalized this limitation was recognized, and the
Common Command Set (CCS) group was formed to solve
this problem by putting together an extended subset of the
SCSI commands. The commands were extended to allow
more detailed information to be sent to and from the device.
A subset of all of the possible commands was chosen to make
it easier for the peripheral device manufacturers. Limiting the
number of commands that a SCSI device must respond to in-
creases the chance that all of them can be implemented. Al-
though the CCS document was not incorporated into the
SCSI-1 specification, it's principles were sound and it was
recognized as a de facto standard to be followed by SCSI pe-
ripheral manufacturers. This helf>ed to reduce the amount of
Figure 3: SCSI Bus Phases
Power c^, r»et or
protocol citui
plug-and-play incompatibilities.
The CCS principles were incorporated into the SCSI-2 spec-
ification. SCSI-2 classifies commands as mandatory, option-
al, or vendor-unique. SCSI de\'ices are required to implement
at least all of the mandatory commands for their device types.
Commands for direct access (disk drive), sequential-access
SCSI Signal Definitions
SCSI signals are carried on two sepi-
arate cables. The A cable contains the
18 signals defined in the SCSI-1 spec,
and the B cable contains the new def-
initions of SCSI-2, 29 in all. 11 signals
are used for control, and 36 are used
for data (including parity). (See Fig-
ures 4 and 5 for the conductor as-
sigments for the A and B cables,
respectively.)
REQ (request): Driven by a target
to indicate a request for a REQ/ACK
data-transfer handshake (for DB7-0).
ACK (acknowledge): Driven by an
initiator to indicate an acknowledg-
ment for a REQ/ACK data-transfer
handshake (for DBO-7).
REQB (request): Driven by a target
to indicate a request for a REQB/
ACKB data-transfer handshake (for
DB31-8).
ACKB (acknowledge): Driven by
an initiator to indicate an acknowl-
edgment for a REQB/ACKB data-
transfer handshake (for DB31-8).
ATN (attention): Driven by an
initiator,
BSY (busy): Wired OR signal driv-
en by the initiator or target to indi-
cate that the bus is being used.
C/D (control/data): Driven by a
target that indicates whether CON-
TROL or DATA information is on the
data bus.
DB(7-0,P) (data bus 7 to and par-
ity): On the A cable, these lines carry
data back and forth between target
and initiator. Also, each line is
uniquely used by devices to an-
nounce tlieir presence during bus ar-
bitration.
DB(31-8,P1,P2,P3) (data bus 31 to 8
and parities): On the B cable, these
lines carry data back and forth be-
tween target and initiator.
DIFFSENS (differential sense):
Found only on a differential SCSI bus,
this signal enables the differential
drivers on the bus,
I/O (input/output): Driven by a
target that controls the direction of
data movement on the data bus
(with respect to the initiator). Also
used to distinguish between Selec-
tion and Reselection phases.
MSG (message): Driven by a tar-
get during the Message phase to in-
dicate that the data contains message
information.
RST (reset): Wired OR signal that
can be set by any device that resets
the bus. This is normally done at
power-up or when a requested device
does not respond.
SEL (select): Used during bus arbi-
tration by an initiator to indicate that
it wants to select a particular target, or
by the target to reselect the initiator.
The device to be selected is indicated
on the data lines.
TERMPWR (terminator power):
Provides power so that termination
resistors can be positioned at both
ends of the bus.
20 AugustlSeptember 1991
Inside SCSI
(tape drive), printer, processor, write-once (optical disk), CD-
ROM devices, scanner devices, optical memory devices,
medium changer devices ("juke box"), and communications
devices are defined.
Another proposal of the CCS document that was included
in SCSI-2 is the concept of reselection. In SCSI-1, when an ini-
tiator sent a command to a target it would occupy the bus un-
til the target had completed the command. In SCSI-2, the ini-
tiator can disconnect from its target after a command has
been issued. When the command is complete, the target ar-
bitrates for the bus for the purpose of reselecHng the device
that sent it the command. It can then complete the operation
by sending back data and status information. Now that the
the SCSI initiator no longer has to wait for the SCSI target de-
vice to finish a command, it is free to send commands to oth-
er target devices so they can be executed concurrently.
This may be useful in a system that has more than one tar-
get SCSI device, but the more common situation is needing
to send another command to the same target device. The
SCSI-1 spec allowed only a single command to be outstand-
ing from an initiator to a logical device of a target SCSI con-
troller. In the case of disk drives this could be inefficient. Sup
pose, for example, a host CPU gets four separate requests
from the operating system to read sectors that reside on tracks
1, 50, 2, and 52. If it can accept only one command at a time,
the drive will waste a lot of seek time as it goes back and forth.
If, however, all four commands can be sent at once, the con-
troller at the disk can optimize the seek time by reading them
in the order of 1, 2, 50, and 52. Because the host CPU speaks
to the devices on the SCSI bus in terms of logical blocks of
data, it has no idea where (or how) the data is stored on the
device. Therefore, it is impossible for the host CPU to opti-
mize the command sequence before it is sent to the SCSI de-
vice. This feature, called command queuing, has been adopt-
ed in SCSI-2. (Up to 256 commands can be queued.)
For a device to keep track of the many commands it queues
up, a queue tag is assigned to each one, allowing each com-
mand to be uniquely accessed. Once a device has been se-
lected on the SCSI bus and the IDENTIFY message is sent, a
two-byte QUEUE TAG message is sent. The message consists
of the desired queuing function and the identifier of the ini-
tiator. When a target controller reselects an initiator, the tag
message is sent after the identifier. Commands sent without
a queue tag are executed in the order recei\'ed, but only one
can be outstanding, as defined under SCSI-1 standards (this
is to maintain compatibility between queuing and nonqueu-
ing environments).
A third area of concern, SCSI-l's data-transfer speed, has
also been improved in SCSI-2. SCSI-l's transfer rate maxed
out at 5 MB/sec. This limitation was addressed from two dif-
ferent angles. The most obvious method to speed things up
was to add more bits. Today's common 16- and 32-bit pro-
cessors give the impression that SCSI-l 's 8-bit bus is primi-
tive. Consequently, the WIDE option was added in SCSI-2,
adding 24 more data bits for a total of 32. The other method
used to solve this problem was to speed things up. If you
"wiggle" the lines twice as fast you will move data twice as
fast— hence the definition of the FAST option of SCSI-2. >
Figure 4: Conductor Assignments for a SCSI A Cable
Single-
Ended
Signal
Differential
Signal
Cable Conductor Number
Differential
Signal
Single-
Ended
Signal
GROUND
GROUND
GROUND
+DB(0)
GROUND
+D8(1)
GROUND
+DB(2)
GROUND
+DB{3)
GROUND
+DB(4)
GROUND
+ DB(5)
GROUND
+DB(6)
GROUND
+DB(7)
GROUND
4.D8(P)
GROUND
DIFFSENS
GROUND
GROUND
GROUND
TERMPWR
GROUND
GROUND
GROUND
+ATN
GROUND
GROUND
GROUND
+BSY
GROUND
+ACK
GROUND
+RST
GROUND
+MSG
GROUND
+SEL
GROUND
+C/D
GROUND
+REQ
GROUND
+I/0
GROUND
GROUND
1
3
5
7
9
n
13
15
17
19
21
23
25
27
29
31
33
35
37
39
41
43
45
47
49
2
GROUND
-OB(0)
4
-DB(0)
-DB(1)
6
-DB(1>
-DB(2)
8
-DB{2)
-DB(3)
10
-DB(3)
-DB{4)
t2
-DBC4)
-0B(5)
14
-DB(5)
-0B(6)
16
-DB{6)
-DB(7)
18
-DB(7)
-OB(P)
20
-DB(P)
GROUND
22
GROUND
GROUND
24
GROUND
GROUND
2fi
TERMPWR
TERMPWR
2B
GROUND
GROUND
30
-ATN
GROUND
32
GROUND
-ATN
34
-BSY
GROUND
36
-ACK
-BSY
3a
-RST
-ACK
40
-MSG
-RST
42
-SEL
-MSG
44
-C/D
-SEL
46
-REQ
-C/D
48
-I/O
-REO
50
GROUND
-I/O
The AW Tech journal 21
Inside SCSI
Both methods of increasing the data throughput are not
without their respective costs. Because all 50 pins of the SCSI-
1 cable were already used, either the cable must grow or an-
other cable must be introduced to add the additional data
bits. Because SCSI-1 and SCSI-2 devices can co-exist in a sys-
tem, increasing the size of the cable would make intercon-
nections awkward. As a result, it was decided to add anoth-
er cable. The original 50-pin SCSI cable is now known as the
A cable, and the new 68-pin cable as the B cable. FAST SCSI
has the limitation that it will work reliably only in a differ-
ential SCSI bus implementation. Because the timing is tight-
ened during FAST operation, single-ended FAST SCSI can-
not keep up. FAST SCSI also requires that all components in
the data path must support the higher data rates.
The combination of FAST and WIDE SCSI provides a
means to transfer data at a maximum rate of 40 MB/sec. This
may seem impressive, but it's overkill for most of the com-
mon applications of SCSI. After all, a disk can spin only so
fast! SCSI devices do contain RAM memory buffers, and de-
pending on how much and how intelligentiy the de\'ice stores
data from a disk in RAM will determine how effectively the
bandwidth can be utilized. You must also take into account
the speed at which the computer system itself can "swallow"
the data. Generally, it is wasted effort to go to the greater cost
and complexity of adding FAST or WIDE SCSI if the host sys-
tem cannot keep up. As an example, the DMA bandwidth of
the Zorro II system bus in an Amiga 2000 has a maximum
bandwidth of about 3.5 MB/sec. Therefore, a SCSI host
adapter connected to the Zorro 11 system bus of an Amiga
cannot even keep up with SCSI-1. The DMA interface to the
host adapter of an Amiga 3000, however, is located on the lo-
cal 68030 bus and is capable of speeds up to 50 MB/sec.
COMMON ACCESS METHOD
The SCSI bus hardware and software may be well defined
as pertains to the physical and logical interfacing between ini-
tiators and targets, but the interface between the SCSI host
adapter in a computer system and the computer's operating
system is not so clear. Because SCSI is implemented on many
hardware platforms that have different system buses and dif- •
Figure 5: Conductor Assignments for a SCSI B Cable
Single-
Ended
Differential
Signal
Signal
Ca
GROUND
GROUND
1
GROUND
+DB(e)
3
GROUND
+DB(9)
5
GROUND
+DB(10)
7
GROUND
+DB(11)
9
GROUND
+DB(12)
11
GROUND
+DB(13)
13
GROUND
-fDB(14)
15
GROUND
+DB(15)
17
GROUND
+DB(P1)
19
GROUND
+ACKB
21
GROUND
GROUND
23
GROUND
+REQB
25
GROUND
+DB(16)
27
GROUND
+DB(17)
29
GROUND
+DB(18)
31
TERMPWHB
TERMPWRB
33
TERMPWRB
TERMPWRB
35
GROUND
+DB(19)
37
GROUND
+DB(20)
39
GROUND
+DBtZ1)
41
GROUND
+DB(22)
43
GROUND
+DB(23)
45
GROUND
+DB(P2)
47
GROUND
+DB(24)
49
GROUND
+DB(25)
51
GROUND
+DB(25)
53
GROUND
+DB(27)
55
GROUND
+DB(2a)
57
GROUND
+DB(29) .
59
GROUND
+DB(30)
61
GROUND
+DB(31)
'- 63
GROUND
+DB(P3)
65
GROUND
GROUND
67
Cable Conductor Number
2
4
6
a
10
12
14
16
18
20
22
24
26
28
30
32
34
36
38
40
42
44
46
48
SO
52
54
56
58
60
62
64
66
68
Single-
Differential
Ended
Signal
Signal
GROUND
GROUND
-0B(8)
-DB(8)
-0B(9)
-DB(9)
-DB(10)
-DB(10)
-DB(11)
-DB(11)
DB(12)
-DB(12)
-DB(13)
-DB(13)
-DB(14)
-DB(14)
-DB(15)
-DB(15)
-DB(P1)
-DB(P1}
-ACKB
-ACKB
DIFFSENS
GROUND
-REQB
-REQB
-DB(16)
-DB(16)
-08(17)
-DB(17)
-OB(ie)
-DB(18)
TERMPWRB
TERMPWR
TERMPWRB
TERMPWR
-DB(19)
-DB(19)
-DB(20)
-DB(20)
-DB(21)
-DB(21)
-DB(22)
-DB(22)
-DB(23)
-DB(23)
-DB(P2)
-0B(P2)
-DB(24)
-DB(24)
-DB(25)
-DB(25)
-DB(26)
-DB(26)
-DB(27)
-DB(27)
-DB(28)
-DB(28)
-DB(29)
-DB(29)
-DB(30)
-DB(30)
-DB{31)
-DB(31)
-DB{P3)
-DB(P3)
GROUND
GROUND
22 AugiistlSeptember 1991
Inside SCSI
ferent hardware implementntions of the SCSI host adapter,
there is a great need to mask differences with a standard soft-
ware interface. Also, some hardware platforms make no pro-
visions for the SCSI host adapter to be used with different de-
vices attached to it. hi an effort to resolve these issues, an ad
hoc industry committee called the Common Access Method
(CAM) committee was formed. One goal of CAM is to pro-
vide similar software interfaces across hardware platforms,
minimizing the effort involved in creating device-driver soft-
ware for a new system.
Using the CAM approach, the operating system depen-
dencies translate the system request into a CAM structure
that is passed to the CAM model. Within the CAM module,
the structure is translated into SCSI hardware instructions
and a SCSI command. Upon completion of the command, sta-
tus is then returned to the user application.
SCSI'S PHYSICAL REQUIREMENTS
The SCSI spec defines all the SCSI bus signals that need to
pass between the devices. This signal information can be
transferred via two methods: single-ended SCSI or differen-
tial SCSI. (A particular SCSI bus implementation is either one
or the other.) The logic level of a single-ended signal is de-
termined by the voltage of a single wire compared to the
common ground. A differential signal requires two wires,
and its level is determined by comparing one of the wire's po-
tential to the other. While re(.]uiring more complex interface
drivers, differential SCSI is less susceptible to electrical noise.
According to the spec, differential SCSI can be used for cable
lengths up to 25 meters and a single-ended implementation
is good for up to six meters. While differential SCSI may be
appropriate when implementing a local area network (LAN)
via SCSI, its added cost and complexity is usually not war-
ranted in a system with a single host adapter.
The SCSI spec requires a 50-conductor cable for the manda-
tory A cable and a 68-pin cable for the optional B cable. Al-
lowable connectors for the A cable come in several shapes:
low-density shielded (which looks like a Centronics printer
connector), low-density nonshielded {.l"x .1" ribbon connec-
tor), and high-density shielded and nonshielded. The B cable
connector may be only high-density shielded or liigh-densi-
ty nonshielded. The high-density connectors were not de-
fined for SCSI-1, but were necessary so that both connectors
could fit on the back of even small peripherals that support
the SCSI WIDE option.
Internal connections for all SCSI host adapters for the Ami-
ga conform to the low-density nonshielded standard speci-
fied in SCSI. Connections to the outside world, however, do
not follow the standard. Although the 25-pin cable used for
external connections does handle all the signals required for
a single-ended SCSI bus, 25 of the ground wires have been
sacrificed in the interest of space. Because there are still six
ground wires remaining, the cable does perform adequately.
(As a side note, Apple also uses the 25-pin external connec-
tor.) When attaching peripheral devices that conform to the
standard connector, you wUl need adapter cables.
To ensure that signal quality on the SCSI bus is maintained,
termination of the bus is required at both ends. In general, all
SCSI devices come with the resistor packs for termination in-
stalled. If the device is not at either end of the cable, you should
remove the resistors. More than two sets of termination resis-
tors on the bus may cause the interface to fail, because the line
drivers are not designed to handle the extra current.
THE THIRD GENERATION
Although SCSI-2 has not yet officially been put to bed,
work is already underway to define the new features to be
adopted in SCSI-3.
Although the WIDE SCSI capability increased SCSI's band-
width, the method in which it was implemented left many
people unsatisfied. The issue of a single cable versus two sep-
arate cables was a hot debate while SCSI-2 was being de-
fined, and it still is. A compromise proposes that the 68-pin
B cable be used as the primary cable providing a 16-bit data
path and that an optional second 68-pin cable provide an-
other 16 bits of data if desired. You could connect both the
68-pin SCSI-3 and 50-pin SCSI-2 devices to the same cable, be-
cause there would be nine new signals added to each side of
the 50-pin connector.
The ability to connect more than eight devices to the bus
would be another nice addition. If the 68-pin cable becomes
the standard, then eight more data lines will always be avail-
able for asserting device IDs, allowing up to 16 devices. Fast
data rates and increasing numbers of devices on the cables
promise to tax the bandwidth (and reliability) of single-
ended SCSI buses. To counter this, a suggestion is before the
committee that differential SCSI become the only option. De-
creasing the specified maximum length of single-ended ca-
bles, however, may still make the 68-pin cable an option in
compact systems.
As an alternative to electrical cable to connect SCSI de-
vices, some folks have suggested that optical driver technol-
ogy be used. Optical driver technology has the advantages of
reducing bulky cable interconnections and dramatically in-
creasing the physical distance between devices. This some-
what radical approach would require a dramatic departures
Figure 6: A3000 SCSI Implementation
Host Adapter
A3000
SYSTEM
RAM
If
32
Ji,
/
SDMAC
FIFO
t
WD33C93
^ FIFO
SCSI
V
The A W Tech Journal 23
Inside SCSI
from the current bus concepts and definitions, however, and
it is more likely a candidate for definifions a generation or
more beyond SCSl-3.
Another area being addressed is the concept of bus fair-
ness. During bus arbitration, the device with the highest ID
always wins out. This can leave devices with low IDs starv-
ing to use the bus. Although prioritization of devices is some-
times beneficial, some method needs to be provided to give
the low priority guys a break once in a while.
Finally, a concept analogous to the Amiga's autoconfig
may find its way into the SCSI definition — automatic con-
figuration of SCSI bus IDs. No matter which suggestions
make the cut, you can be sure the SCSI standard will keep
growing with the times. ■
Greg Berlin is an eight-year veteran of the Commodore engi-
neering staff. He zuas one of the principal designers of the A3000
hardware and is currently involved in the design of future high-end
Amiga si/stems. Write to him cjo The AmigaWorld Tech Jour-
nal, SO Elm St., Peterborough, NH 03458.
The Amiga 3000 SCSI Host Adapter
The A3000 uses a single-chip SCSI
controller, the WD33C93, to construct
the SCSI host adapter. The WD33C93,
from Western Digital, contains its
own microcontroller, which greatly
reduces the overhead required in the
system to manipulate and monitor
the SCSI interface. The WD33C93
pins connect directly to the SCSI bus
to create a single-ended signal con-
figuration.
The host CPU side of the interface
is handled by the Super DMA Con-
troller (SDMAC) gate array on the
A3000's motherboard. This device al-
lows data to be sent via DMA off the
SCSI bus into memory. As data comes
in from the SCSI bus, it is stored in a
small internal byte-wide FIFO in the
WD33C93. As this HFO fills, the data
is output to a 4-x-32-bit FIFO in the
SDMAC chip. When its FIFO is full,
the SDMAC requests the local bus
from the 68030 and empties its FIFO
into system RAM, 32 bits at a time.
The bus is returned to the 68030 and
the process is repeated until all the
data has been received from the SCSI
bus. (See Figure 6 for an illustration of
the A3000 SCSI implementation.)
The WD33C93 was designed to
support the SCSI-1 implementation;
therefore, WIDE SCSI is not support-
ed. Pin-compatible versions of the
WD33C93 that support some addi-
tional characteristics of SCSI-2 are
now available from Western Digital
{WD33C93B). Although these devices
do support FAST SCSI, it should not
be used, since it requires a differential
SCSI bus.
—GB
Who Helps Amiga Pros?
BIX -- the online service for people who know Amiga.
Q Connect with the Comnaodore technical team
Q Get quick answers to tough coding questions
□ Interact with other Amiga Developers
a Download source code, udlities and other programs
□ Keep up with the latest Amiga developments
□ Send and receive private e-mail with binary attachments
a Chat with other Amiga pros in real time
All for just $39 for three months plus $3 per connect hour weeknights and weekends or $6 per
connect hour weekdays via BT Tymnet.
Don't miss out! Just have your computer and modem call 800-225-4129 or 617-861-9767 and
subscribe on-line. It's easy, at the Login prompt enter bix and at the Name? prompt enter
bix.amiga.
EIX
800-227-2983 or 603-924-7681
24 Augusl/September 1991
The Basics of Ray Tracing
Last issue's 3-D object viewer graduates
to a higher level of sophistication.
By Brian Wagner
PHOTO-REALISM IS a popular catch phrase among com-
puter graphics developers and users alike. One technique at
the forefront of this explosion is ray tracing. From a pro-
gramming standpoint, ray tracing is extremely elegant. With
it, creating such dramatic effects as shadows, reflections, and
even refractions (bending of light) is very easy.
To illustrate the basics, t'il wa!k you through a small pro-
gram (called tracer) that generates images of 3-D objects us-
ing the ray-tracing rendering technique. Don't set your hopes
too high: This is not a super-sophisticated ray tracer. I kept
the example program simple, so the concepts would be as
clear and understandable as possible.
Before we begin, you need to know a few things about
how tracer %vorks. The first consideration is the 3-D object for-
mat it represents. For this example, I chose the GEO format
introduced by VideoScape 3-D (Oxxi/Aegis). Because it is
an ASCII format, you can create and edit the objects with just
about any text editor or word processor. (For a full descrip-
tion of the GEO object file format, refer either to the Video-
Scape 3-D documentation or the ReadMe file in the Wagner
drawer of this issue's disk.) To describe how to view the ob-
ject, we give tracer another ASCII file. This viewing-descrip-
Hon file will contain the following information:
Where we are located
Ttie position we are looking at
Ttie fraction of ttie screen to use
LIgtit source position
View window size
Position of the ground
Center ot projection (eye location}
In practice, of course, it will contain coordinates in 3-D
space and numeric settings instead of words. For example:
50
000
1.0
- 50 so 50
500 500
250
(For more details on the basic 3-D coordinate system —
axes, planes, vectors, and so on — see "Building a 3-D Object
Viewer," p. 15, June/July '91. In this article, we'll assume
that the coordinate system is defined as shown in Figure 1.)
The final option we need to send tracer is the size of the
screen to use. We'll use values between 1 and 4 to represent
the following screen resolutions (sizes):
1 320x200
2 320x400 »
Hgure 1 : The 3-D coordinsle system.
Figure 2: A pilot sees rellecled llglil rays passing through his windshield.
The A W Tech journal 25
Ray Tracing
3 640x200
4 640x400
You will actually have more control over the image size
because one of the vievving-description file's parameters de-
fines which fraction of the screen to use. In other words you
can specify, for example, that the program render in only 'A
or 'A of the screen.
Putting it all together, a sample tracer connmand line would
look like:
tracer objectflle viewflle screenmode
If you want to skip ahead and look at the program now, feel
free. Keep in mind, however, that the program itself only
writes RGB files (.red, .gm, .blu), which must be converted
into a picture for viewing. 1 included the pubhc domain pro-
gram View in the Wagner drawer for doing so. (Refer to View's
documentation for more information on viewing RGB files.)
MODEL VIEWS
To make some sense of the values in the viewing-descrip-
tion file, let's define the model we will use to understand ray
tracing. Imagine a pilot silting in his cockpit looking out of
the windshield at the world. The only reason the pilot sees
anything at all is that light (most likely from the sun) is re-
flecting off the environment around him and then passing
through the clear windshield into his eyes. (See Figure 2.)
Granted, this is an extremely basic description of how we
"see," But, as you will discover, it is exactly the approach to
take when ray tracing a picture. Now, imagine that the
plane's windshield is actually your computer's screen. When
you sit and use your computer, you are the pilot looking
through/at your windshield/screen. If we use this relation-
ship, you can view anything that is on the far side of the
monitor. 1 know, that would mean that our object would
have to be inside the monitor to be viewed through the
screen. As this isn't too feasible, we simulate this situation in-
side the imaginary 3-D world of axes and planes. One way is
to suppose that the windshield/screen is the XY plane, which
XY P
ane
VIEWER
Figure 3: The windshield Is the XV plane; the pilot Is on tlie Z eiis.
26 AugustlSeptembcr 1991
V^
VIEl^R
Figure 4: Following every ray Irom ihe light source wastes a loi of effort.
kJ
VIEWER
Figure 5: Following sight rays back to Ihe source is more efficient.
places the viewer somewhere on the Z axis. (See Figure 3.)
The distance of the viewer from the XY plane is very im-
portant and is specified in the viewing-description file as the
center of projection (eye location). This distance effectively
defines the "field of view," which can make the difference be-
tween a flat-looking image or a fisheye effect. I will explain
this value in more detail later.
With this scenario, any objects that existed on the other side
of the XY plane could be visible. I say "could be visible" be-
cause the object is not necessarily "in view." (You'll see how
this is determined a bit later.)
Ray Tracing
HIT
VIEWER
Figure 6; V/hun you score a sight^ray fiil, calculale tte lighl teaching the oblecl,
VIEKER
Figure 7: If the llghl source is blocked from the object, Ihe object has a shsdow,
Remember, light reaching the pilot's eyes defines what he
sees. In our case, we'll have a light source, which is specified
in the viewing-desi:ription file, to shed light on the object. If
we tried to simulate the true physics of light, we would have
to follow large numbers of light paths as they left the Hght
source. Firsl, we'd have to check if any of the paths hit the
object, and then if any passed through the windshield/screen
(or XY plane) to the viewer (from now on, I will refer to the
XY plane as the "viewplane" and the viewer as the "eye"). It
could take forever to chase random paths (rays) from the
light source to see if they ever reached the eye, and only a
small fraction of the light rays we followed would reach the
eye at all. (See Figure 4.)
This is where we reverse nature's process. Computer
graphics ray-tracing algorithms are actually backwards ray
tracers. Instead of tracing light rays from the light source, we
will trace "sight" rays from the eye (viewer) backwards,
through the viewplane (XY plane), into the scene, (See Fig-
ure 5.) This %vay, we can determine exactly what is visible at
any location on the viewplane. We will use the light source
only when we actually hit the object with a ray. When we
score a hit, we will calculate the amount of light that reach-
es the point on the object. (See Figure 6.)
Of all the trademarks that make ray tracing famous (shad-
ows, reflections, and refractions), I will restrict the discussion
to shadows, as they are the easiest to produce. Consider our
example for determining the amount of light that reaches a
particular spot on an object's surface. In the case of a shad-
ow, light is blocked from the surface position being "shad-
ed." To check for this, we test to see if anything lies between
the surface point and the light source. If the light is blocked,
the surface point gets no light and remains dark. That's it —
instant shadows! (See Figure 7.)
The remaining element in the vieiving-description file adds
the final enhancements to our simple ray tracer — a ground
and a sky. We will use the ground-level specification to de-
scribe where the ground lies. The sky will be rendered ev-
erywhere "above" the ground value. Although it may not
sound like it right now, this really is a simple effect.
STRUCTURED COMMENTS
With the 3-D stage set, we are ready to examine the code.
The first file, the header file tracer.h, contains all the structure
definitions and a few constant definitions. For example, the
Polygon structure below describes a single polygon:
struct Polygon {
SHORT cnt;
SHORT -vtx;
FLOAT nx, ny, nz;
SHORT r, g, b;
};
(Note: 1 assume that you are familiar with the concept of
describing objects with polygons and vertices. If you are not,
please refer to "Building a 3-D Object Viewer.")
The first field, cnt, is the number of verfices in the polygon.
The second field, *vtx, is an array containing indices into the
list of the object's vertices. The next three fields, nx, ny, and
nz describe this particular polygon's surface normal. Surface
normals are simply direction vectors that define which di-
rection the polvgon is facing. (We'll talk about this in more
detail later.) The last three fields, r, g, and b define the color
of the polygon as a mix of red, green, and blue. Each color
value can range from to 255,
Tlie next structure is the Vertex structure, which simply
contains the XYZ coordinates of a point in 3-D space:
struct Vertex {
FLOAT x,y,z;
1; •
The AWTech Journal 27
Ray Tracing
Keep in mind that these locations are used to define
a polygon's shape.
We will use the third structure, Ray, to describe a ray.
struct Ray {
FLOAT ox, oy, oz;
FLOATdx, dy, dz;
};
It is really quite simple; rays need to have only a starting
point and a direction defined. The first three fields define the
ray's starting point in 3-D space, and the last three fields de-
scribe the direction the ray travels from the starting point.
Following Ray is the Triangle structure:
struct Triangle {
FL0ATx1,y1,z1;
FLOAT X2,y2,z2;
FLOAT x3,y3,z3;
FLOAT nx, ny, nz;
1;
As you will see later, we can efficiently check to see if only
a triangle and ray intersect. Therefore, we will break the ob-
ject's polygons into triangles before testing for intersections.
The Triangle structure holds these intermediate triangles.
The first nine values define each of the triangle's three ver-
tices, while the last three values define the triangle's surface
normal.
In turn, the Intersection structure holds information relat-
ing to the intersection of a ray and a polygon (or triangle)
when one occurs:
struct Intersection {
FLOAT ix, iy, Iz;
FLOAT disi;
VOID 'poly;
1;
The first three values define the exact location in 3-D space
of the intersecfion. The distance from the eye to the intersec-
tion point is stored in dist. Tlie final field is a pointer to the
Polygon structure of the polygon that was hit.
The three values in the Color structure:
struct Color {
SHORT r, g, b;
};
define the polygon's color as described earlier.
Finally, the ViewOpts structure holds all the information
in the viewing-description file:
struct ViewOpts {
FLOAT cax, cay, caz;
FLOAT Ipx, Ipy, Ipz;
FLOAT scl;
FLOAT Isx, Isy, Isz;
FLOAT vpx, vpy;
FLOAT wdy;
FLOAT cpd;
1;
The first three fields define where the eye is located, and
the following three define the position in 3-D space at which
the eye is looking. The scl field describes which fraction of the
screen to use. We'll use this value to scale the width and
height of the screen mode specified in the command Une, let-
ting us create images that cover, for example, only 'A, 'A, or
Vs of the screen. This feature allows the user to generate quick
test images. The next three fields define the location of the
light source. The location of the light source in relation to the
object determines which portions of the object appear light
and which appear dark. The vpx and vpy fields hold the ac-
tual width and height of the viewplane. These values, among
other things, control zooming or how large or small the ob-
ject appears.
The wdy field houses the ground's position on the Y axis.
We need only a single height value because the ground is an
infinitely large plate that lies parallel to the XZ plane. The last
field, cpd, is the eye's distance from the viewplane or how far
the eye is from the XY plane on the Z axis. (Remember that
we decided the viewplane is the XY plane and the eye is at a
point somewhere on the Z axis.)
TYING IT ALL TOGETHER
The program begins in the tracer.c file. First it checks that
the user specified the correct number of arguments. If the
user did, tracer opens the Graphics and Intuition libraries,
then allocates buffers to hold the polygons and vertices of the
object. Next, the program allocates the three RGB buffers,
one for each primary color, red, green, and blue. As we trace
rays through each pixel on the screen, the color that results
will be stored in these three buffers.
Following all buffer allocations, the program opens the
screen and window, sets the color palette, and removes the
title bar. The screen will have only two colors — black and
gray. As we trace through the pixels, tracer turns them gray
on the screen to indicate that they have been processed. We
remove the title bar because we need to see the entire screen.
As a final preparation, the program initializes a few glob-
al variables. We set npoly and nvert to zero because the ob-
ject has yet to be loaded. Then we set gnx, gny, and gnz to
indicate a vector pointing straight up the Y axis to initialize
the ground as lying in the XZ plane.
Now we are ready to load the object- and viewing-de-
scription file. First tracer calls the loadobjectO function and
passes it the first argument the user specified in the com-
mand line (the object file's name). As the actual loading code
is fairly straightforward, we won't waste any time going over
w
/T\
Figure 8: 'four viewer can by anywhere in 3-D space. To display !he view, rotate the scene.
28 August/September 1991
Ray Tracing
Figure 9: The surface normal ol a polygon face.
it. The program loads the viewing-descripHon file and places
it in the global vopts structure by calling loadvoptsO.
With ever)'thing opened, allocated, and loaded we can be-
gin the rendering process, which is broken down into four ma-
jor functions. The first to be called is transformO (located in
math.c). In it, the object, light source, and ground normal are
all transformed into the viewplane coordinate system. This is
a little tricky, so pay close attention. Remember that we are
using the XY plane as the viewplane, but you can specify
where the eye is located in 3-D space, and it could be looking
at any other location in 3-D space. (See Figure 8.)
If we always use the XY plane as the viewplane, we need
to rotate/ move the object, light source, and ground normal
to get the same view of the object from the XY plane as we
would from the arbitrary location in 3-D space. If you don't
fully understand this concept, don't worry. It should become
more clear as we continue. Keep in mind that this operation
greatly simplifies the actual ray-tracing process. (We won't
dig into the actual details of this function, as you can find a
detailed explanation in "Building a 3-D Object Viewer.")
After the transformation is complete, tracer calls calcnor-
matsO (in math.c). This function steps through each of the ob-
ject's polygons and calculates the polygon's surface normal
using the vector cross-product operation. (Again, the details
of this process can be found in the previous article. For now,
it is important to know ordy that surface normals are simply
direction vectors that indicate the direction in which a poly-
gon faces. See Figure 9.)
FIND THAT RAY
Lef s begin ray tracing by calling the traceimageO function
(located in image.c). Notice that tracer passes this function a
pointer to our window's rastport. We will need this to turn
the pixels gray as they are traced. The rather complex formula
that leads off the function:
ar = (scrw * ((scrh * 4.0) / (scrw * 3.0))) / scrh;
calculates a scaling value used to compensate for the fact that
monitors are not square. This difference in width and height
is indicated by the aspect ratio. The above formula uses an
aspect ratio of '/\ which is common to most monitors.
Next, the program moves the width and height of the view-
plane out of the global vopts structure and into the local vpx
and vpy variables:
vpx = vopts.vpx ■ ar;
vpy = vopts.vpy;
Notice that the width is scaled by the aspect ratio value.
The width and height values (which originally come out of
the viewing description file) are very important. When we
start tracing, we are going to shoot rays through each pixel
on the screen out into 3-D space. Therefore, we need to relate
the screen size (in pixels) to an equivalent in the 3-D world.
The exact values used are actually dependent on the size of
the numbers that describe the object,
As a general rule, the width and height should be equal (as
specified in the viewing-description file) and about 'A the
largest dimension of the object. For example, if the largest ob-
ject dimension were 1000, a good width and height would be
500. These values can, of course, be larger or smaller. In fact,
you can use them to zoom the final image in or out. Smaller
values will make things appear larger, while larger values
will make things look smaller.
Tlie next two lines calculate exactly how many pixels will
be traced:
actw = scrw * vopts.sci;
aclh = scrh ' vopts.sci;
Here we use that scaling value from the viewing-descrip-
Hon file to scale the original width and height of the screen
(in pixels). Finally, we set the dravring color to pen number
one — gray.
We begin tracing by starting two loops, one for the width
and the other for height. This will allow us to cover the spec-
ified range of pixels by working top to bottom, left to right.
Each pixel is handled on an individual basis. The beauty of
the ray-tracing algorithm is that it deals with each pixel, one
at a time. Instead of examining the object's polygons and fig-
uring out which pixels to set to which color, the program
goes backwards and looks at the pixel first.
We want to create a ray that starts at the eye and passes
through each pixel. Because our screen full of pixels is rep-
resented in 3-D space by the XY plane, this is very simple:
px = (FLOAT)l+0.S;
px = vpx * ((px / actw) - 0.5);
py = (FLOAT)(acth - 1 - j) - 0.5;
py = vpy • ((py / aclh) - 0.5);
The first tvvo lines find the horizontal, or X-axis, position.
The last two find the vertical, or Y-axis, position. Because
they are very similar, we will examine the first two lines only.
px = (FLOAT)! + 0.3;
adds 0.5 to the pixel's X coordinate because we want to deal
with the center of the pixel.
px = vpx * ((px / actw) - 0.5);
converts the pixel location into the range of 0.0 to 1.0 by di-
viding the pixel's X coordinate by the total number of pixels
to be traced horizontally. Subtracting 0.5 from this value en-
sures that it falls in the range of - 0.5 to 0.5, Finally, we mul-
tiply by the viewplane width (stored in vpx). >
The AYJ Tech journal 19
Ray Tracing
The same process produces the Y-axis position in 3'D space.
The difference is that the position is reversed because vertical
screen coordinates are reversed from those in 3-D space.
With the pixel's location in 3-D space stored in px and py,
lef s build a ray. First, we calciJate it's origin. Simple: The ori-
gin is the eye position and the eye lies on the Z axis. There-
fore, the X and Y coordinates are both zero. The Z coordinate
is set to the center of projection (eye location) specified in the
viewing-description file. Remember, because the viewplane
is at the center of the Z axis (0), this value specifies distance
from the viewplane. (See Figure 10.)
With the origin set, we calculate the ray's direction. Be-
cause the direction will be from the ray origin through the
previously calculated pixel location, we create a vector by
subtracting the ray's origin from the pixel location. After con-
verting this vector into a unit vector (a vector with a length
of 1), we store the ray direction in the Ray structure.
FOLLOW THAT LIGHT
Now that we have a ray, we can "trace" it and see what, if
anything, it hits. First, the program initializes the intersection
structure, isec, to indicate that there is currently no hit. Then
it loops through all of the polygons and, by calling the poly-
gonhitO function (in mnth.h), tests to see if the ray intersects
any of them.
At the heart of every ray tracer is the code that tests for in-
tersections between a ray and some shape — in our case, a tri-
angle. Because our polygons can be larger than triangles,
however, we must also test the polygon in triangular pieces-
for intersection. The polygonhitO function does the neces-
sary break-ups and calls the trianglehitO function (also in
math.h) to check for intersection. (See Figure 11.)
The code that performs the triangle/ray intersection test is
quite complicated, so we will go over it on a basic level only
(study it at your own pace). First, the ray is checked to see if
it intersects the plane in which the triangle lies. If so, the rou-
Figure 11: Break a polygon inio triangles belore lesting lor lay interseclions.
9-tddow F«t»li
Ina Rau
'■-J Cente
Kr-ojoct iun
Figure 1Q : The center 01 projection specilles the eye location and lis distance hom the viewpltne.
Figure 12:Checkloragioun(lhit,lhenany objects thai block the light.
tine checks to see if the intersection point is either behind the
ray origin or if it is beyond an intersection already found. Re-
member, we want to end up with the closest intersection. If
the intersection is found to be "good," the routine concludes
by determining whether this intersection point actually lies
inside the triangle. If the answer is yes, the intersection point
and distance is stored in the supplied intersection structure
and the function returns.
All the polygons are checked in this manner. After the ray
is checked for intersection with all the polygons, it is checked
to see if it intersects the ground, via the groundhit() function
(in math.h). This function is really the same as the first part
of trianglehitO. The ray needs to be checked only to see if it
intersects the XZ plane at the Y-axis location specified in the
vievidng-description file. In addition, ground hitO returns true
only if the intersection is closer than any of the triangle/ray
intersections.
If a ground hit is found, the ground will appear at that pix-
el, so it needs to be shaded. The first step in this process is to
check if this point lies in shadow. To test this, we call shad-
Contimied on p. 63
30 August/September 3 99 J
TNT
Technical News and Tools from the Amiga Community.
Compiled by Linda Barrett Latlamme
Official Words from CATS
In response to the often-heard statement "What this mar-
ket needs is consistency across applications" comes the Ami-
ga User Interface Style Guide. Written by CATS, it describes
how an apphcation's user interface should look and operate,
setting forth Commodore's interface standards for the Work-
bench, the Shell, and ARexx. The guidelines are backed by
definitions, descriptions, and illustrations of each of the in-
terfaces. As only behavioral guidelines are presented, both
creatively and technically minded interface designers can
benefit. If you can't wait to find a bookstore, you can order
the Ainign User Interface Style Guide directly from Addison-
Wesley Publishing Company (Jacob Way, Reading, MA
01867/800/447-2226) for S21.95 ($28.95 in Canada).
For hardware-minded registered developers, CATS is of-
fering an Amiga 3000 schematics manual for S35 (plus S2.50
for Canadian shipping, $5.00 for overseas). Direct your re-
quests to CATS Orders, 1800 Wilson Dr., West Chester, PA
19380 and ask for part number 314677-02.
Be a Winner
Want to win $10,000? If
you are working on (or have
finished) a program or de-
vice that would benefit the
physically or learning dis-
abled, here's your chance.
Johns Hopkins University
is conducting a National
Search for Computing Appli-
cations to Assist Persons
with Disabilities (CAPD).
Sponsored by the National
Science Foundation and MCI
Communications Corp., the
National Search is a compe-
tition for ideas, systems, de-
vices, and software that are
creative and affordable solu-
tions to the problems faced
by the disabled. The grand
prize for the best computer
program or device is $10,000,
and over 100 additional
prizes will be awarded. Re-
gional winners will be select-
ed in December at science
museum exhibitions across
the country.
The top 30 regional win-
ners will be invited (all ex-
penses paid for the top 10) to
exhibit at The National Exhi-
bition at the Smithsonian In-
stitution in Washington, DC,
on February 1 and 2, 1992.
There the grand prize winner
and top 10 national winners
will be honored.
Entry fliers are available
from CAPD, PO Box 1200,
Laurel, MD 20723. The dead-
line for entries is August 23,
1991, but don't let the short
timeframe deter you. Nation-
al Search officials promise to
expedite last-minute entries
by fax or other means when
necessary.
Optical Fish
Compatible with CDTV and ISO-9660-type CD-ROM
drives, the Fred Fish Collection on CD-ROM disc houses
410 floppies worth of the Fred Fish software library. The col-
lection is provided both in its original form organized by I'Q.Ster/ I'aSter
disk and, as a bonus for BBS sysops, compressed by disk
into .zip files. Several tools (including SID and PKAZIP) are
included in the disc's root directory to facilitate file man-
agement. Available from HyperMedia Concepts Inc. (PO
Box 85303, Racine, Wl 53408, 414/632-3766), the Fred Fish
Collection on CD-ROM sells for $69.95 (plus $2.00 shipping
U.S., SIO foreign). As the collection expands, registered
users may purchase updates every four months for $29.95
each. If you prefer to plan ahead, consider a subscription:
$109.95 for the original disc and two updates. If you are a
registered Amiga developer, call HyperMedia Concepts
about their discount plan.
Great Valley Products wants to speed up your Amiga with
its Series II accelerator systems. Topping the line, the GVP
A3050 ($2999) is a 50 MHz 68030 accelerator board that comes
populated with 4MB of 32-bit memory (expandable to 32MB),
and a SCSI controller. Available optional drives are the Max-
tor one-inch tall 120MB model or a half-height 340MB mod-
el. GVP also offers 22 MHz and 33 MHz 68030 models. The
22 MHz board comes standard with 1 MB of RAM and can be i
TliL-AWTcch Journal 31
TNT
expanded to 13MB, while the 33 MHz version is shipped
with 4MB of RAM and can be expanded to 16MB. For com-
plete pricing, contact Great Valley Products, 600 Clark Ave.,
King of Prussia, PA 19406, 215/337-8770.
r^
Where's the Tail?
Tired of the same old input
devices? Consider the Air-
Mouse Remote Control
($595), a bidirectional in-
frared, point-and-click input
device. Designed with pre-
sentation software and CDTV
titles in rrdnd, the two-button
remote unit will work up to
seven meters from its base-
station, which connects to
your CPU via the serial port.
Current drivers support OS
1.3 and CDTV, but a 2.0 driv-
er is on the way.
Should you have a special
implementation in mind,
check out the Developer
TooIKit. For S4995 you receive
a developer-styte AirMouse
remote and basestation, plus
PoinI and click Irom seven melers away.
drivers for the Amiga, MS-
EXDS, Windows 3.0, and Mac-
intosh 6.0.x. If you have any
problems, Selectech provides
developer services. Contact
Selectech Ltd., 30 Mountain
View, .Colchester, VT 05446,
802/655-9600.
Cheat Sheets
You went to the trouble of programming keyboard equiv-
alents for menus choices, but now your users complain they
can't remember the commands. Rather than hire a larger
technical-support staff, consider K/B Optimizer custom
keyboard templates and reference cards. Templates and
cards are constructed of high-impact, UV-rated polypropy-
lene plastic and coated with a waterproof, scratch-resistant
plastic matte finish to elimnate glare. If none of their stan-
dard configurations will do, K/B promises to custom design
templates and cards to your specifications. Pricing depends
on quantity, ranging from $24 apiece for 10 templates
($29.95 apiece for 10 cards) to $5.35 each for 1000 templates
($9.95 each for cards). For exact prices and more details,
contact K/B Optimizer, PO Box 877, Gardiner, MX 59030
406/848-7320.
Faster and Sharper
If the standard Amiga display modes aren't enough for
your software, consider Digital Micronics Inc.'s 60 MHz
DMIOIO ($1095) and DMI020 ($1995) graphics processor
boards for the A2000, A250C), and A3000. Both offer pro-
grammable control up to their maximum resolutions
(1024x800 for the DMIOIO, 1280x1024 for the DMI020). The
DMIOlO's eight-bitplane system uses a 24-bit, 16-miIlion-col-
or palette with 256 active colors and over 800,000 available
pixels, while the DMI020's 24-bitplane system offers 16 mil-
lion colors and over 1,3 million pixels. If that's sttH not enough
power, the DMIOIODB ($195) memory buffer option for the
DMIOIO promises to increase display speed or up resolution
to 1280x1024, The DMI020's memory buffer option
(DMI020DB, $595) doubles the available VRAM to speed up
screen display. For further information, contact Digital Mi-
cronics Inc., 5674-P EI Camino Real, Carlsbad, CA 92008,
619/931-8554.
'/
I!
Pass the Word
Run across any hot products,
PD sofhoare, or neios? We luaiit
to here about it. Send the details
to TNT, The AmigaWorld
Tech Journal, 80 Elm St., Pe-
terborough, NH 03458. m
32 AugiistlSeptember 3991
r/
^
The AmigaWorld
Tech Journal Disk
^
This nonbootable disk is divided into two main directories,
Articles and Applications . Articles is organized into subdirec-
tories containing source and executable for all routines and
programs discussed in this issue's articles. Rather than con-
dense article titles into cryptic icon names, we named the
subdirectories after their associated authors. So, if you want
the listing for "101 Methods of Bubble Sorting in BASIC," by
Chuck Nicholas, just look for Nicholas, not lOlMOBSIB. The
remainder of the disk, Applications, is composed of direc-
tories containing various programs we thought you'd find
helpful. Keep your copies of Arc, Lharc, and Zoo handy;
space constraints may have forced us to compress a few files.
With the exception of the 2.0 include fdes (which are dis-
tributable only under license), the supplied files are freely dis-
tributable. Do not, however, resell them. Do be polite and ap-
preciative: Send the authors shareware contributions if they
request it and you Uke their programs.
Before you rush to your Amiga and pop your disk in, make
a copy and store the original in a safe place. Listings provid-
ed on-disk are a boon until the disk gets corrupted. Please take
a minute now to save yourself hours of frustration later.
If your disk is defective, return to Amiga Worid Tech Jour-
nal Disk, Special Products, 80 Elm St., Peterborough, NH
03458 for a replacement.
ne AW Tech journal 33
REVIEWS
RxTools \ #^
Where ARexx meets Intuition.
By Eric Giguere
AREXX, THE INCREASINGLY
popular interprocess-control protocol
that Commodore adopted under
AmigaDOS 2.0, is a faithful Amiga
implementation of the powerful REXX
language. Because REXX was de-
signed for console-oriented systems —
not graphical user interfaces like the
Amiga's — it comes as no surprise that
ARexx lacks windowing and menuing
functions. Thanks to ARexx's expand-
ability, however, you can add Intu-
ition-like capabilities to your ARexx
scripts.
There are two ways of adding func-
tions to ARexx. The most common
method is to use an ARexx function
library, which is an Amiga shared
library that ARexx can access. (The
ARexx mathematics library, Rexx-
MathLib, is an example of a function
library.) An often easier method is to
use an ARexx function host. A func-
tion host is simply an ARexx-compati-
b!e application program capable of
processing special messages from
ARexx. TTR Development's RxTools
package is such a program.
The RxTools software comes on a
single bootable disk that includes not
only the host, but also an extensive set
of tutorial files and a simple RxTools
script. To use RxTools, you need ei-
ther Workbench 2.0 or Workbench 1.3
along with the ARexx software pur-
chased from William Hawes. You
should have at least one megabyte of
memory, as the function host itself is
almost 400K in size. A hard disk is
also recommended. If you wish to
share your RxTools scripts with oth-
ers, they too must buy the package.
To access RxTools' functions, you
must run the rx_tools.exe program in
the background. RxTools provides an
initialization sequence that your
ARexx scripts can use to find out
whether the function host is running,
and to start it if not. The initialization
sequence also adds the function host
to the ARexx Library List (the list of
all function libraries and function
hosts that are active) so that ARexx
will send it a message when it needs
to locate a function.
BUILDING WITH OBJECTS
RxTools is based on the principles
of object-oriented programming
(OOP). There are many books that
describe OOP in detail, but here's a
quick primer: The basic entities in
OOP are known as objects. In RxTools,
for example, a vN'indow is an object.
Objects have certain attributes; a win-
dow has a size and a position, for
instance. Objects also allow you to
modify those attributes through vari-
ous methods; RxTools provides a
method to move a window, for exam-
ple. A method can be thought of as a
procedure or function call, but one
that is intimately associated with —
actually a part of — an object.
Methods and attributes are not very
interesting without another (X)P
feature known as class inheritance.
Each object is a member of a class of
objects. All objects in a class share
attributes and methods, though of
course each object has its own data
space. For example, two windows
both have a movement method, and
both have size and position attributes,
but the values of the two sets of at-
tributes may be different. You can
build nev\' classes out of old classes
simply by adding or modifying at-
tributes and methods. Each child class
inherits the attributes and methods of
its parent class unless the new class's
definition specifically overrides them.
In RxTools, for instance, the console
class is a child of the window class.
Hence, a console object has all the
capabilities of a window object plus a
set of methods specific to creaHng and
using an Amiga console device. Class-
es also have methods, but these are
used mostly to create new objects.
Although object-oriented program-
ming seems strange at first, if you
play around with it for a while, you
will likely find it to be quite elegant.
To be truly elegant, however, OOP
requires a programming language
designed with objects in mind. While
ARexx is not an object-oriented lan-
guage, RxTools manages to get
around that restriction. RxTools in-
cludes a reasonable set of object class-
es: menus, various classes of windows
and consoles (including a functional
text editor), file requesters, and some
basic gadgets.
Let's dissect a simple RxTools script
to get a better feel for the program. AH
RxTools scripts start with the follow-
ing statement:
r An RxTools Script v
interpret getcllp( Yxtoolsinll' )
This rather strange statement does
two things; It retrieves a string from
the ARexx Clip List and then uses the
INTERPRET instruction to execute the
contents of the string as if they had
been typed into the script. Tlie string it
retrieves must have been previously
installed in the Clip List by executing
the rxtools.rexx ARexx script, which,
as you will recall, also starts the Rx-
Tools function host. The string holds a
series of ARexx statements that per-
form various initialization tasks, in-
cluding ensuring that the RxTools
function host is still alive (in case a
pre\dous script has terminated it),
opening a notification port, and assign-
ing useful values to a set of variables.
The next step is to open a window
by calling the RxTools function host:
my_wlndow_send('r)(_console',_OPEN,
10, 30, ,250, 80, 'My Window' )
(Keep in mind that if you want to split
an ARexx statement across two or
more lines, each line except the last
one must end with a comma. Such
commas are skipped by the inter-
preter, so the example above really has
seven parameters, not eight.)
The _send() function is an RxTools
function that "sends a message" to a
M AugustlSeplember 1991
class. In RxTools terms, sending a
message to a class or object means
invoking a method on that class or
object. Do not confuse tliis with the
Amiga's built-in interprocess commu-
nication (IPC) facilities. In this case, the
_send() function is invoking the
_OPEN method of the rx_console
class, with four integers and a string as
parameters for that method. This will
create (open) a window of class
rx_console at location (10,30), width
250, height 80, and title "My Window"
on the Workbench screen. The re-
turned string is a handle identifying
the newly created window.
Once the window has been opened,
you can display a string of text in it by
using the following function call:
call send my_wlndow, _PUT_STRING,
'Hello world'
(The call instruction is used to invoke
this function because the return value
is unimportant.) Notice how this time
we use the send( ) function instead of
_send(). The leading underscore
makes a difference: _send() invokes a
method on a class, whereas sendO
invokes a method on an object. This
particular sendO sends a _PUT_
STRING message to the window ob-
ject just created. PUT_STR1NG takes a
string and outputs it at the current
cursor location.
Now we come across another of
those interesting INTERPRET
statements:
interpret gelcllp{ 'rx_tools_ewent_handler' )
This retrieves and executes another
string from the Clip List. This particu-
lar string waits for messages (of the
IPC type) to arrive at the script's noti-
fication port, calls a function in the
script, and then watts for another
message to arrive. Any statements
following the event handler (the
INTERPRET statement) will not be
executed unless they are part of an
ARexx function.
What kind of messages does the
notification port receive? It depends
on the objects that the script defines.
For example, most windows send a
\a\ mmim
irasE
Wi¥iMiWp#iWW'i*|)WWiWW#i^^
31M
Current file; hdisk2:fbn.zoo
linUMMIII
Itiiii or enter a am
pmrmrrmmmmmmmm
mmmms
jj jjl ^^j^^j^^ gjjjj ^j l jjm m
mmmmmmmmm
Arciiive hdisk2;fbH,zoD:
Lengtii CF Size Noh Date
AnisaVision.infD
CED
CED.info
Disk. info
JPaint III, info
Eiiptii.info
fbn.zoo
41688 37;^
43598 m
45132 m.
52284 37/
58788 m
42548 37/
13572 31/
56184 37/
26426 12 Ha
27528 12
28257 12 Ha
33891 12 Harll
36993 12Harl^
iJrives iParentrCAHCEL
26941 12 Har 9B 15;21;25 fbn/fliMst
9344 12 Har 98 15:21:38 fbn/fbinfo
35574 12 Har 98 15:21136 fbn/fbH2poil
oJ
L
f
i?
An Inluilion inlertice lor Zoo by RiToois.
CLOSEWINE>OW message when the
user clicks the window's close gadget.
The event handler receives this mes-
sage and immediately calls the
CLOSEWlNE>OW() function, which
might be defined as foUows;
CLOSEWINDOW: procedure expose packet
parse arg the_window
call send thewindow, CLOSE
call send the_wlndow, DELETE
call reply packet,
exito
This routine closes and deletes the
window that received the close event,
and then terminates the ARexx script.
(A script that opens several windows
would include code to exit only if all
windows have been closed.) Most
object definitions include, as a param-
eter, the name of a function that is to
be called when an event for that object
occurs. For example, you could add a
string gadget to the window using the
statement:
call send my^window, _ADD_STRING
GADGET, 'StringGadget', ,10, 10, 100
When the user enters a string in the
gadget and presses RETURN, the
event handler receives an event and
calls the StringGadgetO function,
which can then retrieve the string
from the gadget and process it. An
RxTools program is basically just a
collection of ARexx functions that get
called whenever events occur.
That, in a nutshell, is the skeleton of
an RxTools program: Initialize Rx-
Tools, define and initialize all the ob-
jects, define the functions that the ob-
jects call, and then start the event loop.
CLIMBING AND BROWSING
The set of all classes in an OOP
environment forms what is known as
a class hierarchy, or tree, because
every class is ultimately a descendent
of some root class. This hierarchy is
important because it lets the program-
mer quickly determine how the vari-
ous classes are related. You will find a
class tree at the back of the RxTools
documentation.
A good OOP environment includes
a class browser, a tool that allows the
programmer to traverse the class tree
and view specifics about each class.
The RxTools browser shows the inher-
itance path of a class and the methods
that class and its objects support.
The browser is the most powerful
tool you can use to write RxTools
scripts because its information is com-
plete and up-to-date. The only prob-
lem with the browser as it now stands
is that there is no simple way to cap-
ture its output. Because of the way it
was implemented, all its output is
generated by the function host itself
and hence appears only on the console
where the function host was started.
This limitation is a bug that 1 hope
will be fixed for the next update.
RxTools has other problems as well,
the most serious of which is its docu-
mentation. Not only is the 90-page
manual meager and incomplete, but it »
The AW Tech joimml 35
Reviews
is poorly organized, full of errors, and
lacks an index. The explanations need
to be expanded to describe in detail
what a function host is and how Rx-
Tools does its work. My recommenda-
tion: Once you have installed and
started RxTools, leave the manual in
its box. Use the tutorial examples and
the class browser as learning tools
instead.
Instalhng RxTools is also trouble-
some. The installation procedure
assumes you want RxTools installed
on your SYS: volume, a mistake if the
partition is almost full. An installation
script written in ARexx would be
more flexible, and the ultimate goal
should be an installation script that
uses RxTools lo install itself. Another
problem is that RxTools does not
always clean up after itself. It is not
uncommon for an ARexx program
under development to encounter an
error and terminate. Unfortunately,
RxTools does not free the program's
resources, and so its windows and
screens hang around until RxTools
notices there is no ARexx program to
notify. Even when RxTools is told to
terminate, orphaned screens are often
left behind to eat up valuable chip
memory. Resource tracking needs to
improve.
RxTools' error messages are annoy-
ing. Warning and minor error mes-
sages are displayed in system
requesters, and, under 1.3, the buttons
on the requester overlap with the last
line of text. Serious errors are
announced using the red-on-black
alert requesters, which seem incredi-
bly rude (and reminiscent of a GURU
message) when you consider that at
most the RxTools function host will
crash. (This is not an unlikely occur-
ence, either. I found that some of the
RxTools tutorial scripts crash the
function host.)
RxTools could use a few more ob-
ject.s, including list boxes and horizon-
tal scroll bars. I would also like to see
some support for the new 2.0 gadgets,
windows, and screens — even if those
features are not available to 1.3 users.
Finally, I would like to see RxTools
decreased in size, or at least have
access to a smaller, nonbrowsing
version. The current size almost cer-
tainly precludes its use in developing
commercial products,
FUTURE DIRECTIONS
RxTools is an interesting product
that is almost crippled by bad docu-
mentation and bugs. That's a shame,
considering how much work has gone
into the design and implementation of
the function host. To UK's credit,
however, the company has been quick
to answer questions on BIX and has a
BBS (608/277-8072) for making up-
dates and bug fixes available to users.
TTR is planning to fix many of Rx-
Tools' problems, and to revamp the
manual. At this stage, however, it's
hard to recommend RxToots to the
novice ARexx user. It would be wise
instead to wait for the bug fixes and
the new documentation.
In the meantime, you might want to
look at the RexxArpLib function li-
brary available on BIX or the Fred Fish
disks. It provides many of the same
capabilities, albeit in a different and
much more restricted manner. It is,
however, a good way to play around
with ARexx and Intuition, and it can
help you to decide whether RxTools is
for you.
RxTools
TTR Development
1120 Gammon Lane
Madison, Wl 53719
608/277-8071
S54.95
One megabyte required.
AmeegaView
Routine help for C.
By David T. McClellan
WRrriNG A PROGRAM that pro-
vides a highly interactive GUI inter-
face can be a sticky proposition.
Intuition is function-rich and corre-
spondingly complicated to write for.
ACDA Corp.'s AmeegaView (former-
ly AmigaView) is designed to make
the environment easier to program in
by making certain common operations
simple and to provide consistent
looks-and-feels for applications.
AmeegaView consists of a set of
libraries, include files, demos, and on-
disk documentation for Intuition, IFF,
and graphics functions to call from
SAS/C and MANX Aztec C programs.
ACDA didn't address Modula-2;
Benchmark and the other packages
have their own simplified libraries.
AmeegaView claims to run with Lat-
tice C 5.02 and 5.04 (which became
SAS/C as of 5.10), and Aztec C68/k
3.6a through 5.0b. The documentation
comes on disk, designed to be printed
out as you see fit.
The functions deal with familiar
Intuition objects (screens, windows,
menus, gadgets, and so on), as well as
fonts, polylines, bitmaps, IFF images,
and the like. The difference between
Intuition and AmeegaView is the
approach. With Intuition 1 .3, to open a
screen and a window and add some
custom gadgets and menus, I have to
fill in values on numerous large C
structures and then call several Intu-
ition functions to build the user inter-
face. Using AmeegaView, I can cut out
most of the data-structure initialization
and some of the calls — the Ameega-
View routines fill in the defaults for
me, while allowing me to customize
those I want. For example, here's an
Intuition window-open as compared
to the AmeegaView version:
I* Intuition version */
struct IntultlonBase 'IntultlonBase;
struct Screen LDraw_scr;
struct NewWindow newwin;
struct Window *LDraw_win;
r Open Intuition library, screen, allocate
bitmaps, then */
newwIn.LellEdge = 0;
newwIn.TopEdge = 0;
newwin. Width = WIDTH;
nevnvin.Height = HEIGHT;
newwin.DetallPen = WHITE;
newwin.BiockPen = BLACK;
newwtn.lDCMPFIsgs = CLOSEWINDOW |
GADGETUP I MENUPICK |
MOUSEBUTTONS;
newwIn.Flags = WINDOWDEPTH | WINDOW
CLOSE I SUPER_BITMAP |
BORDERLESS | ACTIVATE;
newwin. FirstGadget = NULL;
newwin.CheckMark = NULL;
newwin.rttle = (UBYTE •) "LittleDraw";
newwin.Screen = LDraw^scr;
newwin.BilMap = LDraw_bltm;
newwlaMlnHeight = MINHEIGHT;
newwln.MInWidth = lutlNWIDTH;
newwIn.MaxHelght = HEIGHT;
newwIn.MaxWIdth = WIDTH;
newwtn.Type = CUSTOMSCREEN;
36 AugustjSeptember 1991
Reviews
II ((LDraw_win = (struct Window *) Open-
Windowf&newwin)) ==NULL)
(
/* and so on */
)
r AmeegaVlew version '/
SCREEN LDraw scr;
WINDOW LDraw win;
amigavlew open(); I" Init AmeegaVlew, open
Amiga libraries */
/■ Open screen, allocate Bitmaps, similar to
Intuition */
/* then... */
LDraw_wln = window^create (LDraw_scr,
0, 0, WIDTH, HEIGHT,
WiNDOWJnput, MOUSEBUTTONS |
CLOSEWINDOW I
GADGETUP 1 MENUPICK,
WINDOW_SpeclalFealLre, BORDER-
LESS I ACTIVATE,
I' It figures out SuperBllMap '/
WiNDOW_SyslemGadgef, WINDOWDEPTH
I WINDOWCLOSE,
WlNDOW^TIile, •■ Little Draw",
WINDOW_BilMap, LDraw_^bltm,
WINDOW_MlnWidth, MiNWIDTH,
WINDOW_MinHelglH, Ml NH EIGHT,
0);
/■ end the argument list */
If (LDraw_win =s NULL)
{
r errors V
J
What AmeegaView does here is
replace the process of filling in a long
C struct and then calling an Intuition
function with the simpler process of
calling a corresponding AmeegaView
function with a few fixed and a num-
ber of optional arguments. The ivin-
dow_create() function, for example,
requires a SCREEN argument and the
left/top/width/height components of
a window. It fills in default values for
the other arguments if you don't spec-
ify them. In the example above, I
chose to fill in a few other slots with
nondefault values, to tell Ameega-
View which input events, special
features, and system gadgets I wanted
on the window. These optional argu-
ments are listed in keyword-value
pairs, as with WINDOW_MinWidth,
MINWIDTH. These pairs can appear
in any order in the list after the re-
quired arguments; the final argu-
ment ends the list. I found this format
easy to use — not much different from
setting up a long printf. With
AmeegaView filling in defaults for
things I normally copied in from oth-
er, earlier programs, I cut down on
source size. The expense, of course,
was in executable size: The Ameega-
View functions added 1.0-12K to a
small program, more to a larger pro-
gram using more of the library.
Windows and screens are a little
easier with AmeegaView, yet not
extremely so. But AmeegaView goes
on to make menu-building, event- and
gadget-handling, drawing, and IFF
pictures easier, too. For example, the
Intuition event-loop process is much
simpler, from:
/* intuition style '!
struct intulMessage 'msg;
ULONG msgclass;
USHORT msgcode;
struct Window 'win;
for(;;)
(
if ((msg = (struct IntulMessage ")
GetMsg(win->UserPort)) == NULL)
{
Wart(1 « win->UserPort->mp_SiaBlt);
continue;
}
msgclass = m5g->Class;
msgcode = msg->Code;
HeplyMsg (msg);
switch (msgclass)
(
/•...•/
}
) r end for */
to:
r AmeegaView style */
EVENT anEvent;
WINDOW win;
/*...•/
input Jnsert(wln); /• Let AmeegaView know to
watch for '/
/* events from win */
for(;;)
(
anEvent = Input_rBadO;
if (anEvent == NULL)
continue;
switch (evenl_cias5(anEvent))
{
/*...'/
}
}
Again, the AmeegaView version is
not trivial, but is much simpler than
the Intuition version. And I can still
get all the information out of the Mes-
sage/Event that I want — the message
class, gadget or menu ID, and so on.
AmeegaView provides simplified
functions for the following kinds of
Intuition objects: Screen, Window,
Menu, Gadget, Image, Border, IText,
Requester, and IntutMessage. Other
Amiga graphical objects supported
include RastPort, Font, BitMap, Layer,
multi-segment lines, and bitmap and
color data associated with images. To
use them, your program must include
Ami ga View/a miga vie w.h, link with
the SAS/C or Aztec C library, and
provide a C routine called clean_up()
with no arguments, for exit process-
ing. It also must call amigaview_
openO before calling any other
AmeegaView routines. After that, it
can open screens and windows; build
and modify menus, lists of gadgets,
and requesters; and draw to its heart's
content.
One of these objects is a very handy
combination of several gadget fea-
tures. A CHOICEGROUP uses a list of
gadgets with mutual exclusion to
provide similar functionality to Radio-
Buttons for MicroSoft-Windows and
the Macintosh. In such a group of
gadgets, only one gadget can be "on"
(selected) at a time; the user can click
on an unselected gadget, tunung it on
and automatically turning off the
previously selected one. These are
handy for implementing "pick one of
these" requestors.
I had some problems with the docu-
mentation. It was apparently written
by a programmer and not very well
organized. Most of the information I
wanted v\'as there, but it was full of
distracting typos. Most of the routines
are reasonably named; all WINDOW
routines begin with window^, for
example, but event routines began
with event_, inputs and even multi-
inputO (although the docs said this
one is obsolete). Capitalization is not
consistent; for example, there is
Continued on p. 60
TheAWTechfournat37
^^
On DisI
<y An Introduction
To Boopsi
The author of 2.0' s object-oriented
Intuition programming language helps get you started.
By Jim Mackraz
PROGRAMMING A NICE user interface under Intuition
in the conventional way is more difficult and frustrating than
it should be. If you are already familiar with Intuition, you'll
find relief in OS 2.0's object-oriented programming support.
The goal of the Basic Object-Oriented Programming System
for Intuition (Boopsi) is to make things at once easier, more
powerful, and more standardized. Boopsi is ver)' helpful for
writing 2.0 "new look" applications, especially in dealing dy-
namically with various font sizes and screen resolutions.
Before we jump into creating all sorts of new and inter-
connected custom gadget objects, we will start by using some
of the ready-to-use classes of objects that are implemented in
Intuition. Most of the important concepts of object-oriented
programming will show themselves as we explore these sim-
ple examples, so if you're familiar with object-oriented pro-
gramming, you will catch on quickly. (For a more technical
discussion of Boopsi, see the 1990 Commodore-Amiga De-
veloper Conference notes.)
ROUGH SPOTS IN INTUITION
First, a little stage setting is in order, We on the design
team have learned a lot about Intuition's strengths and weak-
nesses in the last several years. Here are some fundamental
areas of version 1.3 and earlier that we identified as needing
attention:
• Intuition has proven to be at once too open and too re-
strictive. A button can be represented by any Intuition image,
but nobody specifies or provides the best image to use. At the
same time, the possibilities with Intuition images are rather
limited. To see a standard look in applications, some standard
and well-designed images have to be made easily available
to applications.
• Constructing user interfaces from pieces is sometimes dif-
ficult. It's hard to encapsulate all the components of a scrolling
list, for example, so that you can throw together a scrolling list
and two command buttons in a requester and move on to the
important part of the project: deciding how a scrolling list
and a couple of buttons can bring benefit to the user.
• Intuition support is at a very low level; only the struc-
tures and constants are defined for the primitive image and
gadget constructs. No routines are provided to dynamically
allocate and initialize these nor to convert the data structure
fields (such as VertPot and HorizBody) to meaningful quan-
tities. Procedural wrappers around gadgets and images have
to be provided by the applications progranuner — each ap-
38 AugustlSeptembcr 1991
plications programmer.
• More problems crop up when you try to implement a re-
fined look to all the gadgets and images. The primitive types
provided are not sufficient, and you cannot mix text, line
drawings (borders), and raster images in a linked drawing
list. To create a button with a label centered in a filled-in
beveled box, you must provide the text in one place, convert
your algorithm for drawing beveled boxes into the proper-
size image raster, and provide that raster in a separate place.
• Perhaps the biggest problem with Intuition is that it is not
extensible. Every mechanical improvement in gadget func-
tionality has to be implemented in ROM (or by complete re-
placement of the gadget mechanism). If programmers can be
trusted to exercise good judgement and restraint with re-
gards to standards, then providing programmers with means
to specialize and extend the types of objects implemented in
ROM allows us to reach a much greater level of refinement
in how programs look and how they interact with the user.
BOOPSI COMES TO THE PARTY
On other computer platforms, object-oriented program-
ming has proven itself suitable, almost ideal, for addressing
these kinds of problems in graphical user interface systems.
User-interface data structures are represented as objects with
a uniform procedural interface, often called semimg a message
to an object. An object is not just a data structure, similar to a
window, gadget, requester, or image, but also a handle on the
executable subroutines that operate on the data and define
the object's behavior. A class refers to support for objects of
some specific type. If you wanted phone-number gadgets,
you would implement the phone-number gadget class, and
in your programs create from that class and use some phone-
number gadget objects.
Boopsi is an attempt to bring some object-oriented pro-
gramming to the Amiga, especially to Intuition program-
ming. It shares principles with most other object-oriented
programming systems, but I placed some unusual require-
ments on it, including:
• You should be able to use any programming language
to write programs using Boopsi and predefined classes. If
the programming language is sufficient to implement an
Amiga interrupt handler, then you should also be able to im-
plement new Boopsi classes.
• Boopsi must be small to fit in ROM, minimize its use of
RAM at runtime, and be reasonably fast on modest hardware.
Remember, the core of the Amiga product line is the A500.
• The user-interface classes must be compatible and inte-
grated with existing Intuition concepts. Boopsi has to fit into
the rest of Intuition, not hang off the side. Support for the 2.0
new look was the project's highest priority.
• Applications and classes implemented for them have to
be protected against future changes to the implementation of
system classes. I could not expect every Amiga appUcation
using Boopsi classes to be recompiled because somebody at
Commodore needed to add separate line-width and line-
height parameters in the embossed-box image object data
structure.
To abide by these rules, we had to accept that Boopsi was
not going to be the be-all, end-all object-oriented application
development environment. We decided if it satisfied these re-
quirements and helped solve some of Intuition's problems,
it would be worthwhile. It has already proven of great value
in implementing the new look of 2.0 system gadgets, glyphs,
and requesters.
CREATING BOOPSI OBJECTS
All of the benefits in the world are not going to matter if
Boopsi is just too difficult to use. Let's take a look at Listing
1 and see how it stacks up. This code fragment creates an em-
bossed box image, draws it into a window, and then dis-
cards it.
Listing 1:
struct Image 'boximage;
boximage = (struct Image *) NewObJecl( NULL, "frameiclass",
IA_Wldtti, 60,
lA^Height, 40,
TAG_END );
Drawlfnage( w->RPort, boximage, 20, 40 );
DlsposeObiecl( boximage );
The first of the three program statements creates an image
structure using the Boopsi function NewObject(). (Like al-
most all of the Boopsi functions, NewObject( ) is a function in
intuition.library.) To create an object, you identify the class
of object you want. Here, it is specified by the string frame
iciass, which is an abbreviation of frame image class. This
Rgure V An enlarged view ol a sample BeopsI requester,
class is public, in that it is available for any application's use
and is referenced by its name. When you advance to imple-
menting your own classes, you should start with private
classes that only your application can use. Such private class-
es are identified by a pointer. Here, we pass NULL for the
pointer because the class is public. The class we are using cre-
ates objects that behave like images. In traditional object-ori-
ented programming fashion, frameiclass is a subclass of the
base image class. It is said that frameiclass inherits behavior
from imageclass.
The next several function arguments to NewObjectO are at-
tribute tag-value pairs. The symbols lA Width and IA_Height
are defined (in the include file intuition/ imageclass.h) to con-
stant values that identify (tag) the image width and height at-
tributes. The IA_ prefix in the symbols stands for Image At-
tribute. Following each attribute tag is the attribute value,
here some arbitrary numbers to specify the image width and
height. You can specify as many attribute tag-item pairs as
you want to NewObjectO; you indicate the end of the list
with the special tag value TAG_END.
Passing attribute lists like this in a function call with a vari-
able number of arguments is actually just a device of the C lan-
guage. The formal system interface behind NewObjectO
passes the address of an array of Tagltem structures, which
NewObjectO just assembles on the stack. You can pass ar-
rays, too, and even mix and match variable argument lists
with fixed arrays. (See the documentation and include files for
the new 2.0 utility. library for general information on using at-
tribute tag lists, which pervade the new programmer inter-
faces throughout 2.0.)
You can use the function NewObjectO to create all Boopsi
objects, not only images. In general, an object is represented by
an absh-act pointer. Exactly what it pomts to is often private in-
formation. Ideally, all specification and access of object pa-
rameters would be done via attribute tags and values passed
to functions NewObjectO, SetAttrsO, GetAttrsO, and their
equivalents. That would be obeying a true black-box interface.
As part of the charter of compatibility and making things
fast and small, however, there are some exceptions. In par-
ticular, for image and gadget classes the function NewOb-
jectO returns a pointer to a familiar Intuition Image structure
or Gadget structure, respectively.
You should severely Umit your interpretations of the data
fields in these transparent object struchires, preferably just to »-
TheAWTech]ourrjal39
Boopsi
position and dimension fields for images and gadgets, and
the Nextlmage field for images. When available, always use
the formal attribute mechanisms for changing any data struc-
ture field; do not poke the objects.
USING AND DISPOSING OF IMAGE OBJECTS
Moving on to the second program statement in Listing 1,
we see another compatibility trick. You can pass image and
gadget objects to the Intuition functions that accept images
and gadgets, respectively, as parameters. The function Draw-
ImageO historically has rendered bitmap raster images using
the Blitter. Here, however, Intuition detects that the image
passed is a Boopsi image object and relies instead on the ob-
ject's class implementation to perform the desired action:
Draw an embossed box.
As you will see a littie later, every action on objects, in-
cluding draw, is accessed through a common interface func-
tion named DoMethod( ), which is Boopsi's version of sending
a message to an object. DrawlmageO just
calls DoMethodO for Boopsi images. (The
second example calls DoMethodO directiy,
to illustrate the equivalence.)
The most interesting part of object-orient-
ed programming is probably apparent al-
ready. We do not know how the embossed
box is rendered or even how it is represent-
ed internally. There's a subroutine some-
where that does the right thing, and our only
path to that subroutine is through the object.
If we had an image class whose objects rep-
resented pictures of the phases of the moon,
we might have even less idea how it really
works, but we could call the exact same
function, Dra wImageC ), to get the desired re-
sults. The point is that all we want to do is
draw the thing, not be bothered with the de-
tails. Nor do we want to carefully call some DrawMoon( ) func-
tion when dealing with MoonPhase images.
Applying the same operation to objects of a variety of class-
es, and getting the results appropriate for each type of objects,
is called polymorphism in the object-oriented programming
world. This is where the power lies.
If you've ever been deeply troubled by the fact that Intu-
ition Image, Border, and IntuiText structures each have their
ovm rendering function (DrawlmageO, DrawBorder( ), and
PrintlTextO, respectively), are not self-identifying, and can-
not be intermingled in a linked list, then rejoice: You are al-
ready an object-oriented programmer, and Boopsi puts an
end to this kind of nonsense once and for all.
The third and last statement in Listing 1 also demonstrates
polymorphism. The function DisposeObjectO deallocates
every object returned from NewObjectO, regardless of its dass.
This' can help out certain schemes of resource hracking and
cleanup; it is also convenient tliat you can pass a NULL pointer
safely to DisposeObjectO (and, more generally, to DoMethodO).
NEW-LOOK BUTTONS AND THEIR IMAGES
The 2.0 Amiga user-interface new look makes heavy use of
embossed frames and silkscreened button glyphs. It is com-
mon that a frame must be calculated to enclose some centered
image contents. Also, the colors used to draw system gadgets
depend on the screen they appear in. To handle these and
other new-look requirements, there Is a bundle of useful in-
formation associated v^ith each screen that the fancier im-
ages use to determine their dimensions and colors. The in-
formation is contained in the Drawlnfo structure.
Listing 2 uses a scre^en's Drawlnfo structure to render a
"smart" image object.
Listing 2:
Struct Drawlnfo 'drinfo;
struct ImpDraw drawjHirams;
drinfo = GetScreenDrawlnfo( window->WScreen );
f a new generalization of DrawlmageO *'
DrawlmageState( w->flPort, txixlmage, 20, 40, IDS_SELECTED,
drinfo );
/* Same function wilhoui: the wrapper, using stack-based
arguments.
7
offs«t|>alr = (20 « 16) | (40); r mai^e a ULONG '/
DoMelhod( boximage, IMPDRAW, w->RPon,
offsielpair, IDS_SELECTED, drinfo );
f San-ie again, using DM() the packaged-
parameter version of DoMethodO
*/
draw_params.MethodlD = iM_DRAW;
r identities this struct '/
draw_params.imp_RPon = w->RPort;
draw_params.lmp_Offset.X = 20;
r X and Y are WORDS •/
draw_params.imp_Otfset.Y = 40;
draw_params.imp„State = IDS_NORMAL;
<lraw_params.imp_Drawlnfo = drinfo;
"The power
of object-oriented
programming
lies in
polymorphism. "
DM( boximage, &drawj3arams );
Generalizing the existing function DrawlmageO, a new
function DrawImageStateO has been introduced. This ex-
tends DrawlmageO to provide a pointer to the useful Draw-
Info structure and to specify which state you want your im-
age to render, such as the selected state of a gadget button.
Putting this knowledge in the images lets you fine-tune how
gadgets should look in action, without needing to deal with
more than one image per gadget.
Listing 2 also demcnstrates tvvo equivalent invocations of
DrawImageStateO. Like DrawlmageO, DrawImageState( ) is
also just a wrapper ciround the ubiquitous dispatcher Do-
MethodO. The example shows both a stack-based argument
interface to DoMethodO and an alternative packaging of the
parameters in a sh-ucture defined in intuition/imageclass.h.
The parameters to DoMethod( ) depend on which operation
or method function you are invoking. The method ID used for
DrawImageStateO and DrawlmageO is IM_DRAW. This
method ID dictates which operation the object will perform.
The object's class inspects this ID and dispatches to the ap-
propriate software.
FRAMES AND CONTENTS
Consider putting a text label inside an embossed box. How
big do you make th€i box, and how do you center the text?
Only when the intelligence behind the frame is coupled with
40 AugustlSeptember 1991
Boopsi
the data in the Drawlnfo structure can a perfect answer be de-
termined. The font of the text is clearly important, but so is
the "shape" and thickness of the frame. Ideally, the resolu-
tion of the screen's display mode should play a role in de-
termining the thickness.
The accompanying example programs (in the Mackraz
drawer on the companion disk) demonstrate a few different
ways you can compose image frames with their contents to
get the results you want. Centering text or pictures in em-
bossed frames is only one part of the general layout problem,
but it is enough to see the basic sequence of operations.
First, you have to rely on the intelligence of the framing
object to tell you how big to make the frame for the contents
to fit. Subsequently, you might want to add a little more
space for aesthetics or to shrink or constrain the contents, if
that size frame is too big to fit in the available screen space.
Once you work out how big you want the frame to be, you
can then rely on the frame-image object to tell you how best
to center the contents within the chosen
dimensions.
As far as your interactions with the
frame are concerned, there are two steps:
query the frame for its recommended di-
mensions and, after consideration or ad-
justment, specify to the frame which di-
mensions you want to use, and let it
adjust (center) things appropriately. Both
of these operations are invoked by a call
to DoMethodO for the IM^FRAME
method — this is the first method we have
dicussed without a familiar wrapper
function. Again, the parameters you pass
to DoMethodO for 1M_FRAME are de-
fined by a structure in intuition/image-
class.h. One of the parameters deter-
mines whether you are inquiring about a
recommended frame dimension or specifying the dimen-
sions you decided on.
A NEW-LOOK REQUESTER
Now we'll discuss the more interesting of the demo ex-
amples (boopsi_request.c), which creates a new-look-style
requester with a proportional (slider) gadget in it. It is a "per-
centage requester" and prompts the user to use the slider to
specify some percentage between and 100, inclusive (see
Figure 1 ). System requesters do not have sliders in them, so
tliis is a fine example of extending the system by piecing to-
gether objects from predefined Boopsi classes.
In truth, the example really does not use a requester, but
puts up the equivalent visuals in an Intuition window. For
illustration, the program opens this window on the default
public screen and uses the new Intuition functions LockPub-
Screen( ) and GetScreenData( ) to lay out the request window
before opening it. It is still impossible to get a 100% reliable
prediction of what the border dimensions of the window will
be when it opens, but the program uses new 2.0 techniques
to specify the inner dimensions and lets Intuition worry about
the border thicknesses.
Tlie system requesters, Uke our example, have a handful of
button gadgets, and ours also has a proportional gadget to
specify percentage. The buttons each have an embossed
frame, but the program shares a single frame-image object be-
tween all buttons. The text labels in the buttons are also low-
"The interface
to data object values
is best handled
by using
attribute tags."
overhead in that no IntuiText structures are involved, just
plain ASCII strings.
In addition to the frame image shared by the buttons, there
are a few other image objects, including a special object to dis-
guise the requester IntuiText as an image, a frame for the text
and the slider, and an image object that renders a stipple fill
pattern within the window interior. These images are all
chained together and attached to an invisible surrogate gad-
get so that it is easy to position them together within the win-
dow borders and Intuition automatically updates all of the
artwork whenever it refreshes the window gadgets.
BOOPSI SLIDERS
Boopsi_request.c uses Boopsi classes to create the requester
gadgets as Boopsi objects. The button gadgets are quite spe-
cialized and are designed for the new look. They are partic-
ularly smart about placing a simple text label within the
raised embossed border.
The proportional gadget is also created
as a Boopsi object, and what would any
repackaging of proportional gadgets be
worth if we did not finally dispense with
the incredibly difficult programmer inter-
face to the "Pot" and "Body" values of
proportional gadgets?
As we learned at the begirming, the inter-
face to data object values is best handled by ■
using attribute tags. Three new attribute tags
are defined for propgadclass: PGA_
Top, PGA_Visible, and PGA„Total. These
names come from the common use of pro-
portional gadgets as scroll bars. For that use,
if you had 100 lines of text to display in a 25-
line region, you would specify PGA_Total to
be 1 00 and PG A_Visible to be 25. You would
use the attribute PGA_Top both to specify
and inquire the "top line" displayed. When displaying the first
25 lines of information, PGA_Top would be zero. At the other
extreme, the top line of the last page of display would be 75. In
a future article, I will show how you can arrange to receive ID-
CMP messages for slider dragging only when the value of
PGA_Top changes, which is just what you want.
In our example at hand, we don't want a scroll bar, but a
valuator that takes values from to 100 and increments or
decrements by one for each container cUck. We do this by
specifying PGA_Total to be 101 (0 to 100 inclusive) and
PGA^Visibletobel.
WHEN DO WE START?
As with all of the new features of 2.0, it's a little difficult to
know just when you can use Boopsi in new software prod-
ucts and have a sizable installed base of 2.0 operating systems
out there to run them. While you wait, you might want to use
Boopsi in non-product research projects as practice. When 2.0
ships to the mass market, I anticipate Boopsi will be one force
behind an explosion of new and revised applications that
share the attractive new look and have a new high level of
user-interaction refinement. ■
Jim Mackraz is a cotisidtant ami sofiimre developer living in Pah
Alio, CA. He ivas responsible for Intuition for five \/ears. Write to
hint cjo The AmigaWorld Tech Journal, 80 Elm St., Peterbor-
ough, NH 03458, or contact him on BIX (jmackraz).
The AW Tech Journal 41
System Events and
Event-Handling Routines
Find out who does what to whom.
By Eugene Mortimore
THE AMIGA'S COMPLEX multitasking software system
can appear intimidating to even experienced programmers.
One of the reasons for this apparent complexity is that many
extremely vital routines were preprogrammed into the sys-
tem, thereby saving you much work. Among these are the hid-
den hardware-interrupt routines that allow programs to in-
teract with and respond to real-time outside events. While
always hidden from your direct view, the globally present
Exec-system internal routines maintain order in a system
where outside real-time random events, intertask task-syn-
chronized nonrandom events, and the machinestate transi-
tions they bring about occur in split microseconds. To main-
tain order among all routines (system-predefined and
programmer-defined) that need to share data, memory, CPU
time, and other sometimes scarce system resources, the Ami-
ga software system has a number of bookkeeping mechanisms.
As your programs become more complex, you may won-
der: When is my task routine active? How did it become ac-
tive? What is my task routine doing now? When are other
task routines in the system active? Why do they become ac-
tive when they do? How can I design my task to expedite its
execution? What system- wide information can my task rou-
tine access? To answer these questions, this article will focus
on the functional purpose and behavior of the most prevalent
Amiga routine types. I will also try to make the descriptive
language and the general interactions of Amiga processes,
tasks, interrupts, and traps — and their associated routines —
more precise, to help you place the tasks and routines you de-
fine in the appropriate total system context and understand
the general logic of Amiga multitasking system operations.
Part of this article is concerned with software-interrupt
events and their associated software-interrupt routines. Exe-
cution of these interrupt routines can be initiated by the Exec
Cause function or through the use of software signals and
their associated Exec message ports. Although I confined this
article to the Exec Cause function mechanism for inducing
software-interrupt events, it still illustrates the essential pur-
pose and features of this type of interrupt routine without the
added complexity required to discuss software signals.
THE EXECBASE STRUCTURE'S IMPORTANCE
Key to our discussion is the ExecBase structure, the pri-
mary bookkeeping mechanism for all concurrent tasks in the
Exec software system. The Exec system-internal routines con-
tinuously maintain and update its parameters as task switch-
ing proceeds. This maintenance and updating — the continu-
ous writing of some of its parameters — occurs on a very tight
time scale. (While I will discuss only ExecBase structure pa-
42 August! Sqilember 1991
rameters that relate to this article, you can find the complete
definition in the execbase.h include file.)
Any task can look at (read) the ExecBase structure's pa-
rameters at any time to get a system- wide snapshot of the sys-
tem's most vital cha]-acteristics. For example, the ExecBase
structure TaskReady List substructure contains a system-
wide list of all tasks currently ready to run in the system.
Your task can examine the task names in that list (the list
Node structure ln_Name parameter) to determine which
tasks are currently ready to execute.
In a similar way, the TaskWait List substructure contains
a system-wide list of all tasks currently waiting to run in the
system. These tasks are usually waiting for a software signal.
Your task can examine the task names in that list (again the
list Node structure l.n_Name parameter) to determine all
tasks that are currently waiting to execute,
ExecBase's ThisTask parameter holds a pointer to the Task
structure of the currently executing task. Also, its TaskExit-
Code parameter always contains a pointer to the exit code for
the currently executing task. This exit-code routine could be
designed specifically for the task — and referenced in a par-
ent-task AddTask function call that created the task — or it
could be the system's default task-exit code.
The TaskTrapCodf! parameter houses a pointer to the en-
try point of the current task's currently executing trap rou-
tine. This trap-code routine could be designed specifically
for the task and have a trap number referenced in a task-re-
lated AllocTrap funcfion call.
The IntVects[16] parameter always contains a group of 16
IntVector substructures defining the current system-wide
hardware-interrupt routines. These IntVector structures de^
fine how all keyboard interrupts, vertical-blanking interrupts,
and so on are currently treated.
Each IntVector structure contains a pointer to the code
(iv_Code) and the data (iv Data) of the currently effective
hardware-interrupt ::outine assigned to a piece of Amiga
hardware. These IntVector structures define the current hard-
ware-interrupt routines that are used throughout the system.
Upon system startup, most of these routines and their data
are in ROM. When a specific task calls the Exec library Set-
In tVector and AddlrtServer functions to replace or extend
these hardware-interrupt routines, however, those newly-
defined routines become effective throughout the system and
will be used by all processes, devices, and tasks currently in
the system. For this reason, make hardware-interrupt routine
modifications and amendments with great care and keep an
eye to their impact on other concurrent tasks in the system.
The five List substractures in the ExecBase structure's Soft-»
W-
^^
EACH
i^^;
"^-B^l,
"V
? Exciting
Wew Videos
backed With
^nside Info
^nd Hot Tips!
VIDEO TOASTER
The Video Toaster™ from NewTek is hailed as the world's first video
computer card enabling broadcast-quality production on desktop! TheVIDEO
TOASTER" videotape is indispensable for Amiga owners considering the
purchase of a Toaster" or those curious about all the excitement over this
"revolutionary breakthrough in technology."
VIDEO TOASTER" provides in-depth, comprehensive information on the
Toaster's" wide array of features and amazing capabilities. Topics covered
include installing the Toaster'" in the Amiga 2(X)0; adding and testing other
essential equipment; selecting source material; and manipulation of the many
digital video effects, including flips, tumbles, mirrors, spins, splits and titles.
This video also illustrates how to generate and then superimpose letters over
pictures, how lo produce three-dimensional animations and how to paint on
video images.
See for yourself what the excitement is all about!
HOTROD!
HOT ROD YOUR AMIGA provides authoritative advice on how to achieve
maximum power with your machine, whether you own a series 500, 2000 or
3000 Amiga.
HOT ROD YOUR AMIGA teaches you how to expand memory internally
and externally. U provides valuable, in-depth information on selecting and
installing hard drives, memory boards and accelerators; back-up software and
utilities; RAM and drive .space differences; and other "hot-rodding" tips. It also
covers high-end peripherals such as DCTV" and the revolutionary Video
Toaster"". Don't wait to soup up your Amiga!
PRIMER
THE AMIGA PRIMER video provides step-by-stcp instructions covering the
many features of the Amiga. Whether you're a new owner or an experienced
user, this easy-to-follow video will prove invaluable. Packed with almost 90
minutes of detailed information, THE AMIGA PRIMER teaches you in an
entertaining format with vibrant graphics and upbeat music.
Gain the full benefits that the Amiga has to offer on all Amiga models.
System 2.0 and Amiga Vision^. It also covers the Amiga workbench, the CLI,
peripherals and utilities. There's no easier way to master your Amiga!
sary en Sif3r^3irg
jxwstlu^ penohersJs.
3X10 artl 3000
J
m HURRY
^
W WHILE
-4
SUPPLIES
^^s^jm^
k LAST!
1-800-343-0728
CALL TOLL FREE or mail this coupon.
n— — — — — — — — — — — — — — -I
■ -^ ▼■ I ^ ^^ 1 1 am eager to become ao J
I Y |H ^ I expei^! Please send me the |
I JL I /WJ» followicg videos:
■ Q Video Toaster" i$24.95, $19.95
I Q Hot Rod Your Amiga ^4.95' $19.95
I □ The Amiga Primer m.% $24.95
I □ Animation Video, Vol. One. ..$29.p $14.95
• □ Desktop Video, Vol. One $29W5 $24.95
I □ Amiga Graphics, Vol. One ....$2P.!!5 $24.95
I □ The Musical Amiga $29.9S $24.95
J □ Animadon Video, Vol. 'I\vo...|29.9^ $19.95
I □ Check/Money Order Q MasterCard QVISA QAmEx
' Make checks payable to TechMedia Video. Q Discover
I Please include $2.95 shipping & handling for one video, $5.00 for two or more.
I TotalAmLS
I Aoct.#_ Exp. Date
I Signature
_ Name ^
Address
' City^tate/Zip
I t1j:chMedia
I VIDEO
- PO Box 802, 80 Elm Street, Peterborough, NH 03458 603-924-0100
I An IDG Commimicatioos Company
IAnilil^ in VKS otij. new llkw A^ wceb br i^nrj- fMpl oflkn: vU $7JD fee xinn^
iSvnj; SIS fat nn ot mt YidBoi. Tijans sx he oadi a US. fok tem w Ui laali.
ITsUlnM Vite k Ik kawd Krt Alsioi AljMot rf A/lipWoU Vidm iW. »«,
1»1 bj »jm Wto USA. M lU^ BaoKi *««p » 1 B^mml niiMik »l C«««*B
bant MKliM^ Ik. VUn tbau k a admtilNtWM, kc DCTV k 1 rateuk c< Dtaal
L._. I
Event Handling
Intsl5] parameter define the software-interrupt routine queues
of currently pending software-interrupt routines. The Exec
system assures that software-interrupt routines always exe-
cute ata higher priority than tasks, but at a lower priority than
hardware-interrupt routines. One use for software-interrupt
routines is to modularize your tasks into micro tasks that ex-
ecute on the side and do not require explicit task bookkeep-
ing — no Task structure. Another is to allow any extensive-
hardware-interrupt-related processing to be deferred until all
currently pending hardware-interrupts are completed.
Finally, the ExecBase structure Quantum parameter is di-
rectly related to the time-slice round-robin time-quantum pe-
riod allowed for each task to execute when round-robin mul-
titasking is occurring. From now on, I will use the term
Quantum to refer to the actual number of seconds between
task switches. At present, the system sets Quantum to 16 in
version 1.3 of the operating system, and to 4 in OS 2.0. While
Quantum is a small time integral, it is a sufficiently long pe-
riod for a large number of task (68000 assembly-language) in-
structions to execute before task switching reoccurs.
SYSTEM-CREATED TASKS VS. PROGRAMMER-
DEFINED TASKS
As a programmer, you will spend most of your time pro-
gramming and debugging your own programmer-defined
tasks. As discussed above, in the most common circumstance,
these program-process tasks will be automatically created by
the system software whenever it creates an AmigaDOS pro-
cess associated with your program. The Exec and Amiga-
DOS system software automatically work together to create
a program-process task when your program is launched from
the CLl or Workbench. At that time, the system software will,
in essence, allocate and initialize a Process structure and its
associated Task structure, automatically setting appropriate
structure parameters to allow the system software to main-
tain the bookkeeping on your task.
While most of the time the system software handles task
bookkeeping, occasionally you might create a task inside
your program source code by allocating and initializing a
Task structure and, in effect, simulating the system software's
setup duties. In either case, it is helpful to know how your
tasks fit into the total scheme of things: what your task-re-
lated programming responsibilities are, what the system does
for you, and how the system behaves when your task exe-
cutes and interacts with other tasks and other task routines
concurrently in the system. The best approach to under-
standing these task-to-task interactions is to focus on the gen-
eral sequence of system events and study the behavior of
task and other routines that execute during that sequence.
This way you will begin to fathom the functional nature of
the various routine types and then be able to focus on the sys-
tem's flow of control and relate it to your known program-
ming requirements and the fixed constraints in the system.
To this end, let's take a look at the general flow of execu-
tion among programmer-defined-task and other task-related
routines in our multitasking system. If you concentrate on the
main principles highHghted here, you wUl better understand
general Amiga programing principles and the specific se-
quence of task-related events, as tasks are continuously
switched in and out of execution on a very-tight time scale.
Your new understanding in turn will give you a better grasp
of the context in which you program and in which your soft-
ware executes. This will help you avoid competing with or
duplicating the respcmsibilities and actions of the Exec or
AmigaDOS system internal routines, letting you take full ad-
vantage of what the sj'stem can do for you. You can use these
insights to better understand the interactions among your
program-defined task routines and both system-predefined
and programmer-defined task routines that are concurrent-
ly executing in the system.
THE GENERAL SEQ UENCE OF TASK -
EXECUTION EVENTS
We will focus on tlie interaction of programmer-defined
task routines, predefined hardware-interrupt routines, pro-
grammer-defined hardware-interrupt routines, programmer-
defined software-interrupt routines, programmer-defined
software- and hardware- (68000 processor) trap routines, and
the system internal routines. These categories cover all the
types of routines you will need to consider. While there may
be other mechanisms for creating and then initiating execu-
tion of these routines — for, example, software signals — these
are the only routine types understood by the Amiga multi-
tasking system. Because Amiga multitasking is a complex
subject, it is very useful to look at simplified situation that de-
picts the most important routine scheduling mechanisms.
Figure 1 illustrates two tasks and shows how the multi-
tasking system works. Each could be a short graphics task,
either a standalone task or an AmigaCXDS process task, that
draws figures in an Intuifion window by calling Graphics li-
brary functions. Notice that I arbitrarily divided each task's
code into four blocks. You could create these tasks either as
explicit tasks within another program (spawn them as child
tasks) or as separate program-process tasks whose simulta-
neous execufion is somehow started from a CLI window or
a Workbench icon.
The first block of code contains task inifialization state-
ments and is where you open libraries the task requires and
allocate and irutialize: the dynamic structures the task uses.
For a graphics task in an Intuition window, you would open
the Graphics and Intuifion libraries and allocate and initial-
ize Screen, Window, and perhaps Rastport structures here.
The second and third blocks are for code that accomplish-
es operations specific to the task. For a graphics task, this
would include calls to the Graphics library funcfions that
draw graphics in your newly opened Intuition window.
The fourth block houses the code to clean up your task.
Here you would close your opened Ubraries (Graphics and
Intuition) and free any memory blocks you allocated in oth-
er parts — most probably the first block of your task code. If
you modified the interrupt system, you would here restore
the interrupts appropriately.
Figure 1 draws attention to the relationship between the
Exec system code, th-2 programmer-defined task code, hard-
ware-interrupt code (system-predefined and programmer-
defined), programmer-defined software-interrupt routine
code, and any programmer-defined trap routine code as-
signed to the task. The Exec system code, while not explicit-
ly shown in the figure, is the ever-present low-level code that
manages everything else in the system; it is the system-soft-
ware traffic cop. As cur discussion unfolds. Figure 1 will also
help clarify the fundional distincdon between hardware in-
terrupts, software interrupts, and the two types of Motorola
68000 trap events in the Amiga system.
One of the keys to understanding the Amiga multitasking
system is knowing tlie difference between synchronous and
44 AugustlSqjtember 1991
Event Handling
asynchronous events. Tliis difference is easiest to understand
in the context of two identical concurrent tasks. In general, if
an event can occur at any time, it is an asynchronous event.
If an event can occur only when a section of a task's code has
been entered and a specific program instruction executed, it
is a synchronous event. This distinction will become clearer
as we discuss our two-task example in detail.
The two large rectangles represent the executable code of
two separate tasks. The entry and exit points (first and last
assembly-language instructions) for the tasks are at the top
and bottom of the rectangles, respectively.
INTERRUPT ROUTINES AND EVENTS
The inward-pointing arrows at the top of these two rect-
angles depict the action of the system's elapsed-time count-
down routine that initiates task switching every Quantum
seconds. The diagram does not explicitly show a separate
rectangle for the system's task-switching routine, which is the
routine that does the actual s^vitch, changing task register
contexts. In this discussion, it is considered to be one of the
internal Exec system routines. You should understand, how-
ever, that the system's task-switching routine automatically
gets the CPU every Quantum seconds as guaranteed by one
of the Amiga's hardware-chip-countdown registers. Once the
countdown event occurs, the system automatically initiates
execution of the task-switching routine and task-switcliing
occurs. You can classify the system task-switching event as
either an asynchronous or a synchronous event. It is asyn-
chronous because its occurrence is not determined by the
task code. Qn the other hand, it is synchronous because it is
regular and predictable in timing — it does not occur at ran-
dom times.
The inward-pointing arrows on the outsides of the two
task rectangles collectively represent all outside-world hard-
ware-interrupt events that may occur randomly while the
two task routines are executing. These arrows depict the
source of most of the asynchronous events referred to above.
Notice that these arrows point to random locations in the
task code suggesting that they are induced by outside- world
events that occur at random times dvtring the execution of
these tasks, such as the user pressing a key.
The four smaller rectangles in the middle of Figure 1 rep
resent four types of additional routines. These routines may
or may not be directly associated (assigned to the task by the
programmer) with the two tasks. Notice that the entry and
exit points (the first and last assembly-language instructions)
for these four routines are at the top and bottom of their
smaller rectangles. The inward-pointing arrows at the bottom
of these four rectangles collectively depict all hardware-in-
terrupt events that occur randomly while these routines are
executing.
Thus, there is always the possibility that a new, second •
Figure 1: Summary of Events and Event Handling Routines
in the Amiga System.
Hardware
Interrupts
^
Occur at
Random
Times
Other- ^
Hardware
Interrupts
at -1
Random
Times
Task Switched In
1
Task Switched In
Task 1 : User Mode
Block 1
Task
Initialization
Block 2
Cau3e() .
Block 3
Trap _ .
Block 4
Trap #N-
Task Cleanup
^
Hardware Interruot Routine
Executes In 68000
Supervisor Mode
1
Hardware Interrrupl
^
Software Interrupt Routing
' *!.
Executes In 58000
Supervisor Mode
Hardware Interrrupt
-^
68000 Hardware Trap Routine
Executes In 6S000
Supervisor Mode
1
Hardware Interrrupt
¥
Proarammer Defined Trap Routine
Executes in 6BO0O
Supervisor Mode
Hardware Interrrupl
Task 2: User Mode
Block 1
Task
Initialization
Block a
_Cause{)
Block 3
. -Trap
Block 4
.Trap#N
Task Cleanup
Hardware
Interrupts
*
Occur at
Random
Times
«- Other
Hardware
Interrupts
• -- at
Random
Times
TheAWTechjourmliS
Event Handling
(third, fourth, or more) randomly timed hardware-interrupt
event will occur while the interrupt routine associated with
a previous hardware-interrupt event is executing. The Exec
system software must be able to cope with the nested-hard-
ware-interrupt event situation. Hardware-interrupt events
may also interrupt software-interrupt routines, 68000 hard-
ware trap-routines, and programmer-defined trap routines.
(This will become clearer later.)
FLOW OF CONTROL
The dotted lines between aU rectangles in Figure 1 illustrate
the flow of control in the system. When the 68000 program
counter (address) points to the assembly-language instruc-
tions in each of the rectangles in Figure 1, that particular rou-
tine will be executing for a period determined by overall sys-
tem logic and predefined system-scheduling considerations
fixed by the Amiga's task-scheduling logic — a logic that is
embedded in the hidden Exec scheduling routines. Specifi-
cally, in Figure 1, you can see that each task routine is de-
ferred (interrupted) four times to allow a task-related side
routine to execute. The dotted lines (between rectangles) and
the associated terminal arrow heads show that when one of
the tasks is interrupted, execution begins at the entry point
of these "on-the-side" routines (the top of the rectangle) and
ends at the exit point (the bottom of the same rectangle). Con-
trol then returns to the interrupted task at the same point that
the task was interrupted, and its next instruction begins ex-
ecution. Now the CPU program counter once again points to
instructions inside the task routine itself.
For the sake of simplicity, assume that the two tasks have
identical code, such as two copies of the same graphics pro-
gram launched from one Shell. In that case, each task will in-
herit the task priority of the Shell window from which it was
launched. For purposes of discussion, assume a task prior-
ity; tasks will therefore execute in parallel alternately loosing
and gaining the CPU. Under normal circumstances, every
Motorola 68000 instruction that eventually executes in one
task will also eventually execute in the other task before both
truly finish execution. Except for premature task failure or
user-task termination, this result is guaranteed by our two-
identical task arrangement and by the way the Amiga multi-
tasking system works.
No matter how it is brought into existence, each task is de-
fined by its own Task structure and has its own distinct Mo-
torola 68000 user-mode stack specified by its Task-structure
stack parameters. When a program process task is executed
from the Shell or Workbench, the system internal routines
make these initializations, On the other hand, if you spawn
a child task within an already executing parent task, you
must do the initializations.
Assume that the variables taskl and task2 are defined as
C pointers to the respecti\'e Task structures for our t^vo-iden-
tical tasks:
struct Task *lask1, 'tasl(2;
The Task structure, defined in the tasks.h include file, has
the following definition:
struct Task (
struct Node (c_Node;
UBYTE tc_FIags;
UBYTE tc_State;
BYTEtcJDNestCnt;
BYTE tc_TDNe8tCnt;
ULONG tc_SigAlloc;
ULONG tc_SigWait;
ULONG tc_SigRecvd;
ULONG tc_Sig Except;
UWORDtc_TrapAlloc;
UWORD tc_TrapAble;
APTR tc_ExceptData;
APTR tc_E)(ceptCode;
APTR tc_TrapData;
APTR tc_TrapCode;
APTR tc_SPReg;
APTR tc_SPLower;
APTR tc_SPUpper;
VOIDtc_Switch();
VOID tc_Launcti();
struct list Ic MemEntry;
APTR tc_UserData;
);
Several Task-structure parameters must be initialized be-
fore the task is added to the system with the AddTask func-
tion. Once the task is added, the system places it on the sys-
tem's ExecBase struchire TaskReady list. In our example case,
one way or the other, each of these tasks is assigned task
priority by setting the Task structure Node substructure
ln_Pri parameter to 0, which you do as follows:
taskl ->tc_Node.ln_Pri = 0; task2->tc_Node.!n_Pri = 0;
In addition, if the task uses its own trap routines, the
tcTrapCode and tc_TrapData parameters are initialized to
point to the programmer-defined code and data for trap
events and the tc_SP!i^eg, tc_SPLower, and tc_SPUpper pa-
rameters are set to specify the task stack. In our simplified ex-
ample, this is done identically for each task using matching
C initialization statements (with differing Task structure
pointers, of course).
Note that in this discussion, the Task-structure parame-
ters, tc^ExceptCode and tc_ExceptData, used to define the
code and data for soflware interrupts (exceptions) related to
software signals, are not initialized because we are not con-
sidering software signals here. We are considering only the
Exec Cause function mechanism of inducing software inter-
rupts. The Cause function uses the Exec Interrupt structure
to define the code and data to handle the software-interrupt
event. Also, specifically note that the Task structure make no
mention of code and data for interrupt routines. We will see
why later.
THE DETAILED SEQUENCE OF EXECUTION EVENTS
Each task's four cede blocks in Figure 1 (Block! through
Block4) can also be defined by the four types of events that
occur during task execution:
• hardware-interrupt events and the execution of the associ-
ated hardware-interrupt routines
• software-interrupt events and the execution of the associ-
ated software-interrupt routines
• Motorola 68000 internal-hardware trap events and the ex-
ecution of the associated hardware-trap-recovery routines
• programmer-defini.'d software-trap events and the execu-
tion of the associated software-trap-processing routines.
Once the Task structure is allocated and initiaUzed for each
task, that task is added to the system %vith the AddTask func-
46 AngustlSeptember 1991
Event Handling
Hon. When AddTask returns, both tasks are placed on the sys-
tem's ExecBase structure task-ready list. Now the Exec sys-
tem's hidden scheduler routines decide when the first task
gets the CPU. [f, apart from the ever-present system tasks,
these were the only two tasks in the system, the system would
operate as follows:
Phase One
Because, by assumption and arrangement, each of these
tasks has equal zero priority, the multitasking system starts
executing one of the tasks (probably the first one added with
a AddTask function call), and Blockl of its code begins exe-
cution at its entry point. Quantum seconds later, Task2 begins
execution. Tl-iese two tasks each execute for Quantum sec-
onds—first Taskl, then Task2, then Taskl, then Task2— al-
ternately until, by assumption, a randomly-timed hardware-
interrupt event occurs as shown.
Now assume Taskl was in the middle of executing a group
of assembly-language instructions when the first hardware
interrupt occurred. The interrupt is the outside world inter-
acting with the task, asking for 68000 processor time to cap
ture some information that is available only for a brief instant.
This hardware interrupt could have come, for example, from
someone typing at the keyboard or an AmigaDOS copy op-
eration asking for information from the disk. The hardware-
interrupt event couid be completely uru-elated to the task and
therefore ignored, or it could be keyboard activity that sup-
plies data for the task. In any case, as a result, execution of
Taskl code ceases and the (short) hardware-interrupt routine
associated with that particular hardware-interrupt event be-
gins execution.
Just prior to passing control to the interrupt routine, the
Exec-system routines automatically save the current register
context (DO through D7, AO through A6 and the PC and SR
registers) for Task] on Taskl's 68000 user-mode stack. This
is the RAM stack controlled by the Task-structure stack-defin-
ing parameters as described above.
The Exec system-internal routines then put the 68000 pro-
cessor into supervisor mode and the hardware-interrupt rou-
tine currently associated with that hardware-interrupt event
begins execution. If it was a keyboard-interrupt event, the
keyboard-interrupt routine places the new keystroke into the
keyboard input buffer and very quickly returns control to the
interrupted task. The Exec system routines then restore the
previous task context (its saved registers) when the hard-
ware-interrupt routine completes execution.
If this hardware-interrupt routine is part of a linked-inter-
rupt-server routine chain, one or more of the routines in that
chain execute, each in turn until the hardware-interrupt event
is fully processed. This chained-routine arrangement is use-
ful when you want more than one thing to happen with the
hardware-interrupt event occurs. For example, the hardware-
interrupt associated with a math-coprocessor hardware-in-
terrupt event has a linked-interrupt-server routine chain
mechanism. That is, at some point in the ser\'er-routine chain,
determined purely by the preprogrammed internal decision-
making process in the interrupt-server routines and the
specifics of the hardware-interrupt event, server-chain rou-
tine execution ceases, the Exec system internal-scheduling
routines redispatch Taskl. The Exec system routines restore
Taskl's CPU register context from Taskl's user-mode stack
and Taskl resumes execution where it left off.
Here we assume no higher-priority task was added to the
system task-ready list before the hardware-interrupt event
occurred. This assumption virtually guarantees that Taskl
will regain the CPU when the hardware-interrupt routine
completes execution.
Phase Two
When multitasking and task-context switching resume
Quantum seconds later, Task2 begins execution. The system
alternately allows Taskl and Task2 to execute. The Exec-sys-
tem internal routines automatically manage each task's stack,
thereby saving and restoring each task's register context
every Quantum seconds. Again, assume a randomly-timed
external hardware-interrupt event — the same type of hard-
ware-interrupt event as for Taskl — occurs near the middle of
execution of Task2's Blockl code. As with the first hardware
interrupt, the timing of this hardware-interrupt event is ran-
dom; someone hit a keyboard key. The system saves Taskl's
current register context and passes control to the same sys-
tem-wide keyboard-interrupt routine used to process the first
keyboard-interrupt event as for Taskl. Then, very quickly,
the hardware-interrupt routine returns control to Taskl.
Taskl begins executing again at the instruction following the
point it was interrupted.
Phase Three
Quantum seconds later, multitasking again resumes; the
system alternately allows Taskl and Taskl to execute every
(Quantum seconds. The system automatically manages each
task's stack, saving and restoring each task's 68000 register
context every Quantum seconds.
During Taskl's Blockl code execution by task-design as-
sumption, Taskl calls the Exec library Cause function. Cause
tells Taskl to stop executing and transfer control to one of its
software-interrupt routines. As before, Taskl's register context
is saved on its user-mode stack. (Note that the only argument
in the Cause function call is a pointer to a Interrupt structure
representing a particular software-interrupt routine.)
Now, just as with the previous hardware-interrupt rou-
tines, the system places the 68000 into supen'isor mode to
process the software-interrupt routine. Any function calls
(such as shared-library function calls) the software-interrupt
routine makes will use the 68000 supervisor-mode stack.
Multitasking is suspended while the software-interrupt rou-
tine executes.
You must understand that the task prearranges aU the ac-
tions of softvvare interrupts that the Cause function induces
by properly setting the parameters in an Interrupt structure
related to the software interrupt. That is, the task initializes
an Interrupt structure's is_Code and is_Data parameters in
its Blockl code before calHng the Cause function in Blockl.
Thus, the Exec Interrupt structure serves to define both the
asynchronous, outside-world, randomly-timed hardware-
interrupt event routines and the sychronous, task-timed, soft-
ware-interrupt-event routines that the Cause function in-
duces. The Interrupt structure provides a mechanism for a
task to specify a code and data section to accomplish an ar-
bitrary event-processing job, no matter what the source of
that event. Also note that Cause-function-induced software
interrupts are not defined by setting the Task structure tc_Ex-
ceptCode and tc_ExceptData parameters; these parameters
are used for software signal-induced software-interrupt ex-
ception routines only.
Phase Four
Quantum seconds later, multitasking resumes. The instant
Taskl regains control, it calls the Cause function and exe-
cutes the same software-interrupt routine that Taskl previ-^-
The AW Tech journal 47
Event Handling
ously executed. The exact timing of this second software-in-
terrupt event is guaranteed by the assumed symmetry of the
situation; except for using different stacks and different Task
structures, Task! and Task2 are identical-synchronized tasks
with one-for-one identical assembly-language instructions.
When Task2 turns over control to the software-interrupt
routine, the Exec system routines automatically save Taskl's
register context on Taskl's user-mode stack, and the appro-
priate software-interrupt routine executes in supervisor
mode. Control quickly rehims to Task2 routines when the
software-interrupt routine executes an assembly-language
RTS instruction.
Phase Five
Quantum seconds later, multitasking resumes. Taskl now
regains the 68000 processor. The remainder of both tasks'
BlockZ code and part of their Blocks code executes. Once
again, Taskl and Task2 alternately execute Quantum sec-
onds apart. By assumption, at some point a Motorola 68000
hardware-trap event occurs in Taskl. For example, the graph-
ics task performs graphic-coordinate calculations that lead to
an inadvertent zero divisor. When Taskl tries to divide by
zero, the 68000 processor automatically senses this divide-
overflow condition. One of the hardware trap-recovery rou-
tines defined by the system or programmer (the one designed
to deal with zero-divide overflow) executes.
The trap routine should be designed to recover from the di-
vide problem so that the Taskl can continue executing. For
a interactive CAD graphics task, for example, this trap rou-
tine could alert the program user to the zero-divide condition
and ask for the user to supply new program coordinates as
input.
Just as with the hardware-interrupt routines, the system
places the 68000 into supervisor mode to process the hard-
ware trap-routine recovery code. Any function calls made in
the trap routine use the 68000 supervisor-mode stack. Multi-
tasking is suspended while the trap routine executes.
The system automatically saves Taskl's register context on
Taskl's user-mode stack before the trap routine executes. Tlie
last 68000 assembly-language trap-routine instruction exe-
cuted will be RTF (Return from Exception) and Taskl again
quickly regains control. The RTE instruction places the 68000
CPU back into 68000 user mode.
Phase Six
Quantum seconds later, multitasking resumes; Taskl and
Task2 alternate every Quantum seconds. Block3 of Task2 be-
gins execution and, by assumption of symmetry, the same
trap problem occurs: Task2 attempts to divide by zero. The
68(X}0 senses this divide-overflow condition and execution of
Task2 ceases while the divide-by-zero hard ware- trap routine
attempts to allow Task2 to recover. The trap routine finally
executes a Motorola 68CKX) RTE instruction that rehims exe-
cution to Task2. The RTE instruction again places the system
back into 68000 user mode.
Phase Seven
Quantum seconds later, multitasking resumes; Taskl and
Task2 alternate every Quantum seconds. Eventually, Taskl
enters Block4 and executes a 68000 assembly-language TRAP
#N instruction. This allows Taskl to execute an arbitrary pro-
grammer-defined trap routine to accomplish some job out-
side of the coding of Taskl itself— in effect, to perform a soft-
ware-trap routine. The programmer has 16 software-trap
routines available (16 software-trap numbers). 68000 soft-
ware-trap routines are always initiated by the Motorola CPU
68000 TRAP #N instruction.
In this sense, the puipose of programmer-defined TRAP #N
routines is very similar to software-interrupt routines except
that their initialization mechanism is different. Software-in-
terrupt routines are initiated by the Exec Cause function, by a
software-exception sig;nal sent through an Exec message port
or by some other, more direct software-signal mechanism.
Just like a software- interrupt routine, the TRAP #N routine
can be a large routine and is not time-critical as is a hardware-
interrupt routine. Also like hardware- and software-inter-
rupt routines, a trap routine executes in 68000 supervisor-
mode, during whic'i time multitasking is temporarily
suspended. Therefore, note that if the trap routiiie is large, the
trap routine itself should include a call to the Exec UserState
function, to quickly switch back to 68000 user-mode from
within the trap routine. This keeps the essential supervisor-
mode processing short and allows multitasking to continue.
These trap routines provide yet another way to modularize
your code but, because they execute in 68000 supervisor-
mode, are most often used in the Exec system code itself.
As before, the trap routine completely finishes execution
and control rehirns tD Taskl. The last 68000 assembly-lan-
guage trap routine instruction executed is RTE, and Taskl
again quickly regains control, The RTE instruction places the
system back into 68000 user-mode.
Phase Eight
Quantum seconds 1 ater, multitasking resumes and imme-
diately, because of the guaranteed task symmetry, Task2 calls
the same 68000 assembly-language TRAP #N routine, places
the 68000 into supervisor-mode, temporarily suspending
multitasking, and then completes execution and returns con-
trol to Task2. The last 68000 assembly-language trap routine
instruction executed virill be RTE, and Task2 again quickly re-
gains control. The RTE instruction places the system back
into 68000 user mode.
Taskl and Taskl continue executing (Juantum seconds
apart until their respective exit functions are called and con-
trol passes back to the system.
STILL IN THE QUEUE
By now you should have a grasp of the four types of rou-
tines that the Exec library funcHons can understand and man-
age. You can see that the system's CPU is constantly svvitch-
ing among task (and other) routines and between user and
supervisor modes to accommodate all types of system e\'ents.
Note that not all routines must be a direct part of an Amiga
process or task. Inste.id, some routines can be called on the
side as necessary. Keep this in mind as you explore ways to
modularize your program code for maximum efficiency and
reduce the Exec and AmigaEXDS bookkeeping overhead.
If you study our discussion, you will begin to appreciate
how your own program task fits into the total system, when
that task accesses the CPU, and what considerations the Exec
routines use to schedule tasks. To further this understanding,
in the next issue I will expand upon this discussion's most im-
portant concepts and examine the implications and restric-
tions of 68000 supervisor- and user-mode execution and the
proper use of task-related routines. ■
Eugene Mortimorc is a developer and t!w author of Sybcx's Ami-
ga Programmer's Handbook, Volumes I and II. Write to him
cjo The AmigaWorld Tech Journal, SO Eim St., Peterborough,
NH 03458.
48 August/September 1991
^
PostScript Primer
With printer prices falling, the time is right to add precision
graphics output capabilities to your programs.
By Jim Fiore
APPLICATIONS THAT DEPEND on high-quality hard-
copy have no excuse for ignoring PostScript these days. Post-
Script dovetails quite nicely with the Amiga's graphic
prowess, and it is becoming affordable as the prices for entry-
level PostScript laser printers drop, 1 intend to wipe out your
final excuse ("1 don't know how to program in it.") by intro-
ducing you to the fundamentals of PostScript graphics and
adding basic PostScript output support to your applications.
You do not need any sort of "PostScript compiler" to pro-
gram with the language. PostScript laser printers contain Post-
Script interpreters. In effect, when you buy the printer, you are
also buying a miniature language-development system, the
interpreter. (See why PostScript printers cost more than ordi-
nary laser printers?)
HELLO POSTSCRIPT
A page-description language, PostScript is device inde-
pendent. In other words, the quality of the printed page is a
function of the mechanics of the printer, not of the PostScript
code. This is in contrast to the Amiga's graphics library,
which is pretty much hardwired to the Amiga's chip set. A
good portion of the PostScript language is built around the
needs of transferring graphics and text to paper. The balance
of the language consists of the elements you expect in any
high-level language, such as facilities for looping, condition-
als, procedures, definitions, and so on. Unlike such languages
as C, PostScript is stack-oriented and employs postfix nota-
tion. In a statement you first place arguments onto a last-in-
first-out stack, then give the procedure. If you had a proce-
dure called smerzl that took two numeric arguments, a C
language version would look like:
smerzl( 110, 23 );
The PostScript scheme yields a little different statement:
110 23 smerzl
Like C, PostScript is fairly freeform in nature. It lets you in-
clude blank lines and place several items on one line. The per-
cent sign (%) denotes a comment. (Everything after % on a
line is taken as a comment.)
When composing a page you should keep three things
mind: the current page, the current path, and the clipping
path. Empty when you start, the current page is where all
drawing takes place. You draw on the page with opaque
paint; there is no transparency. The current path refers to a
collection of positions, arcs, lines, and so on, and is con-
structed using PostScript operators. This path can be very
complex and can even cross over itself. The clipping path is
the path that defines a printable area. For example, you might
construct a clipping path in the shape of an ellipse. Only ele-
ments contained within tliis ellipse will be printed; anything
that falls outside will be ignored. By default, the clipping
path is equal to the dimensions of the page.
PostScript maps a piece of paper as an X-Y coordinate sys-
tem with its origin in the lower-left comer. A positive X val-
ue moves you to the right, while a positive Y value moves
you up the page. Note that this orientation is somewhat dif-
ferent than the Amiga's, which uses the upper-left as the ori-
gin, with positive Y values moving you down the page. The
default unit is the point, which is defined in PostScript as one
seventy-second of an inch CAz). PostScript's operators will let
you scale the units to your own desire, move the origin, and
rotate the entire coordinate system. By doing so, you can
work within your own ideal "user space." It is the job of the
printer to map the positions onto its mechanics. This is how
device independence is achieved.
Let's take a look at a simple program:
newpath
100 200 moveto
300 400 lineto
stroke
showpage
The newpath command clears the current path and de-
clares that you are about to start building a new one. The sec-
ond line places the values 100 and 200 on the stack and then
calls moveto, setting the current position. The "pen" is now
positioned 100 points to the right of the origin and 200 points
above it. The moveto command is functionally similar to the
graphics library's MoveO. The program's third line draws a
line from the current position to one 300 points to the right
of and 400 points above the origin. Therefore, lineto is simi-
lar to Draw(). Note that no actual drawing has taken place
yet. The stroke command initiates the process of drawing or
painting onto the paper. Why is this extra step required? You
can use the moveto/Iineto commands to create a clipping
path as well, and you may not want the clipping path to be
outlined. The final command, showpage, indicates that all
work on the page has been completed, and that the printer
should create and eject it. While moveto and lineto are based
on absolute positions, you can use rmoveto and rUneto to in-
dicate relative positions. For example:
100 50 rmoveto
means move 100 points to the right and 50 points above the
current position instead of to the right and above the origin. »
T!te AW Tech fotirml 49
PostScript Primer
As you can see, the moveto and lineto operators will
allow you to create two-dimensional graphs with ease.
Repeated calls to moveto and lineto will create an appro-
priate grid for the plot. Once this is completed, you can use
a succession of linetos to connect the data to be plotted.
COPY TO PRINT
To see the results of the above program, the easiest method
is to type the program into a text editor, save it, and send it
to the printer by simply copying the file to the proper port.
For example, if you connect via the parallel port and you call
the program test.ps, the Shell command
COPY test.ps PAR:
will do the trick for you. (If you connect via the serial port,
use SER: instead.) If you send an erroneous program to your
printer, the device will usually just ignore it and do nothing.
Depending on the exact error, it may eject a blank page. While
this technique is wonderful for working out bugs in your
code, it does not help you splice the code into your larger
application.
As all your program needs to do is send strings of ASCII
text from vour program to the printer, the splicing methods
are fairly straightforward. You could open up the appropri-
ate DOS device (SER: or PAR:) and WriteO to it. Generally,
opening PRT: is inappropriate, because the printer de\'ice will
perform character translations, and you want raw character
streams. Another possibility is to use the Exec lO routines. The
Amiga ROM Kenml Mnnual: Libraries & Devices (Addison-Wes-
ley) includes snippets of code that are perfect for this, includ-
ing a "plug-in" function called PrintRaw(). (Personally, I use
the dissidents PrintSpool library as it also takes care of back-
ground printing. You can find it on Fred Fish disk #393.) For-
matting the text strings is done in the normal fashion (C pro-
grammers can use sprintfO, or roll their own).
Shown below is a sample C program that uses the above
PostScript code for a printer connected to the parallel port.
For simplicity, it opens and writes to the DOS parallel device.
The test.ps code is small enough to be placed into a single
string. Larger applications will probably require the use of
several strings and several calls to Write( ).
/* simple PostScript ps.c
For Manx 5.0,
c p3.c
In ps.o -Id
«/
#lnclude "exec/types.h"
Mnclude "functlons.ti"
#lnclude "ilbrarles/dos.h"
ctiar ps_cmd[] = {"newpath 100 200 moveto 300 400 lineto stroice
showpageVn"};
void maln()
1
BPTR Mie;
long Isn;
file = OpenC'PAR:", MODE_NEWFiLE );
if( Hie )
{
len = strlen( ps_cmd );
if( Write( llle, ps^cnd, ien ) 1= len )
putsC'Write erroAn");
C!ose< file );
}
else
putsC'Open (aliure\n"j;
1
GET FANCY
A single line is nice, but nothing special. With two new
commands, you can modify the test.ps program to draw a
box with a different line width.
newpatti
100 200 moveto
100 400 lineto
300 400 lineto
300 200 ilneto
close path
10 setiinewidth
stroke
show page
The setiinewidth command specifies the width of the line
as 10 points. The closepath operator completes the box and
produce a flush appearance. (Replacing closepath with 100
200 lineto will not gi-ve the same results. Because of the added
thickness of the line, a small notch will remain at the start/ fin-
ish point.)
You can create a filled box as well:
newpath
100 200 moveto
100 400 lineto
300 400 Ilneto
300 200 lineto
closepath
.6 setgray
fill
shovrpage
Also new to this e:<ample, the setgray operator allows you
to create grayscales. For solid black use 0, and for white use 1 .
Without some forra of title, axis labels, and numeric scales,
the graphs you build ivith the above commands will not be very
useful. Enter PostScript's text-creation power, PostScript print-
ers contain a set of standard typefaces (such as Times-Roman
or Helvetica), but you can also instruct the printer to use type-
faces that it does not hold internally. Wlien you wish to print,
you must first spedty the typeface and size you want, that is,
specify the current font. Here is a quick sample program:
/Helvetica findlont % u se the Klelevetica typeface
12 scalefont % malce ttiis 12 points high
setfont % make this this current font
100 300 moveto
(Helio World) show % print Helio World at location 100, 300
showpage
Note that you place the text to be printed within paren-
theses and use the show operator.
ALL TOGETHER
Now let's combine the graphic and text elements into one
larger program that draws a filled gray box with a 10-point
50 Augusl/Sepiember 1991
PostScript Primer
thick dark-gray border. Above and to the right of this box it
prints blorg[ at a 10-degree angle. (See Figure 1.)
newpath
% create a light-gray INIed box
100 200 moveto
100 400 lineto
300 400 lineto
300 200 lineto
closepath
J setgray
till
% outline the box with a dari(-gray border
1 00 200 moveto
100 400 lineto
300 400 lineto
300 200 lineto
closepath
10 setlinewldth
.25 setgray
stroke
% malce a 20-polnt Helvetica font.
/Helvetica findfont 20 scalefont setfoni
setgray % set the inl< to blac)(.
300 300 translate % move the origin to the position 300, 300
1 rotate % rotate coordinate system 1 degrees
50 1 50 moveto
(biorgl) show % print the word blorg!
showpage
This example introduces two new concepts. First off, the
translate operator lets you move the effective origin to any
point you desire. After all, appUcations may require an origin
somewhere other than in the lower-left comer. Also, a program
might continually change the origin if multiple data plots or
3-D effects are used. The rotate operator moves the coordinate
system a given number of degrees counterclockwise. The
above example uses this to make the text run uphill.
Note that transposing the first two portions of the program
will subtly alter the page. If the filled-box section is called sec-
ond, it will obscure the inner portions of the surrounding
border, because it is laid down using opaque "paint" (even
when using grayscales, there is no transparency). Before mov-
ing to the next example, try experimenting with the clip op-
erator. The basic idea is to define a clipping path using the
appropriate newpath /moveto /lineto /closepath commands.
When this path is complete, finish with the operator clip.
This sets the clipping path to the one you just defined. Only
areas within the clipping path will be rendered. For example:
% define a triangular clipping region
newpath
100 200 moveto
150 300 lineto
200 200 tineto
Closepath
clip
Try placing this code chunk at the very beginning of the
previous example and watch what happens (Figure 2). Note
that the clip code affects only painting that comes after it.
Figure 1. The setliitewldlh and setgray commands In actlcn.
Figure 2. A trlsngular region clipped Irom Figure 1.
If you are tired of straight lines, a useful operator is arc. Its
general form is:
X y radius l>egin end arc
The command
100 200 30 45 arc
produces an arc centered on coordinate 100, 200 with a radius
of 30. The arc starts at degrees from the horizontal and ex-
tends counterclockwise back to 45 degrees. (The accn com-
mand produces a clockwise rotation.)
For a different perspective, consider the scale operator. Up
to now, the default coordinate system of points C/^z inch)
was used. You can, however, scale the user space, increasing
or decreasing the scales as desired. For example, if you would
like to change the scale to something larger you could say:
100 200 scale
which increases the X axis by a factor of 100 and the Y axis
by a factor of 200.
THE COMPLETE PICTURE
Our last stop on the PostScript tour is the transfer of im-
ages. Such operators as moveto, lineto, and arc are very use-
ful for CAD-type programs, but they are not particularly ef-
ficient when dealing with bitmapped images. PostScript
solves this problem via the image operator. With it, you can »
The A W Tech jounml 51
PostScript Primer
transfer bitmapped images (black-and-white or grayscale).
The image operator's general format is:
width height blts_per_sample transform^matrtx procedure Image
Width and height indicate the size of the image. Analogous
to the "depth" of an Amiga screen, bits_per„sample can be a
value of 1, 2, 4, or 8. For example, 4 means that each pixel is
represented by a 4-bit value. A black-and-white picture has a
bits_per_sample of 1 . The transform_matrix is rather involved,
but in essence, it allows you to map the image data onto the
page in a variety of ways (for example, you could make a
mirror version). For general-purpose image data where the
origin is at the upper left, the transform matrix is [width -
height height]. The procedure parameter is the data to be
used. The image operator takes all of these parameters and
maps the image data onto a "unit square." You can change the
aspect ratio of this square with the scale operator,
A slightly more advanced use of the image command al-
lows you to repeat the image (rather like a pattern) within the
unit square. The data is organized as a series of samples, each
being 1, 2, 4, or 8 bits in length. The value of a sample corre-
sponds to the values associated with the setgray operator.
That is, black is and white is 1.
While it is possible to calculate image values by hand, it is
tedious to say the least. A good tool to have for experimen-
tation is a drawing utility that lets you save the picture in-
formation as C source code, such as Icon2C on Fred Fish #56.
Once you have drawn the picture with the tool and saved its
data file, you must edit it for PostScript consumption. Hex
values in C begin with Ox and individual values are separat-
ed by conunas. Both of these elements must be removed for
PostScript data (search /replace and macros come in very
handy for this).
The following program uses data derived from such a tool.
The image is 32 by 20 and is black and white (one bitplane
deep). The image will be drawn twice, so it is defined as an
element called faceguy using the PostScript operator def.
newpalh
% Image Is 32 wide by 20 high
/laceguy
<tf HHff
f0 3f00ff
b7 9e 7e 7f
ffffffff
fOOfOOfI
e7 e6 7e 7f
cl C6 fc 7f
67 06 78 7t
food 00 ft
fffcffff
fffelfft
e7ffceff
871f8e1f
e7c0 1eff
foftfetf
fc 00 03 ff
(df9dfff
fc fl df <1
feinfff
ff CO 7f ff > def
100 200 translate
72 72 scale% 1 pixel = 1 Inch
32 20 1 [32 -20 20] {laceguy} Image
1 2 tran5late% move right 1 Inch, up 2 inches
2 3 sca1e% twice as wide, three times as high
32 20 1 [32 -20 20] (taceguy) Image
showpage
To see the picture, the coordinate system is scaled to a
much larger size. Also, the translate operator brings the im-
age up and to the right. The second time the program draws
the image, a further translation keeps the two images on dif-
ferent parts of the papier. Note the second translate uses much
smaller values than the first, because the user space has al-
ready been magnified by the 72 72 scale command, A second
scale command shows how you can stretch or distort an im-
age. In this case, the image will be taller and skinnier than
normal. This all worlis fine for black-and-white images. Cre-
ating grayscale images is a bit more time consuming, how-
ever, because most cf the available programmer's drawing
op
op
Figure 3. A rep«aled pattern eieinGnt.
tools save data bitplane by bitplane rather than producing
values for each pixel.
RELAX MODE
As you can see, PostScript programming is not particular-
ly difficult if you have already mastered another high-level
language. Once you test your code, splicing it into the Ami-
ga application is easy. The commands discussed here should
be more than enough, to get you started, but if you would like
to learn more about PostScript's power, I recommend The
PostScript Language Tutorial and Cookbook and The PostScript
Language Reference Manual, both by Adobe Systems Incorpo-
rated and published by Addison-Wesley. ■
Jim Fiore is a member of dissidents, which specializes in Amiga
music and audio softumre. In his spare time he enjoys numerous
hobbies and pursuits zchich liave nothing whatsoever to do ivith sil-
icon or C compilers. Also, he is presently putting the final touches
on an electrical engineering text for West Publishing. Write to him
cjo The Amiga World Tech Journal, 80 Elm St., Peterborough,
NH 03458, or contact him on BIX (jfiore).
52 August/September 1991
Become a part of the
AmigaWorld
Programming Team
We're looking for quality programs to support the growth
of the AmigaWorld product line,
and we need your help.
GAMES
ANIMATION
3D
UTILITIES
CLIP ART
AMIGAVISION APPLICATIONS
OTHER STAND-ALONE APPLICAnONS
We offer competitive payment and an opportunity for fame.
Send your submissions or contact us for guidelines:
Amiga Product Submissions
Mare-Anne Jarvela
(603) 924-0100
80 Elm Street
Peterborough, NH 03458
The AW Tech Journal 53
THE AMIGAWORLD CATALOG
VIDEOS
Order now and save $5.00 off the retail price
and get a $5.00 savings coupon good towards your next
TechMedia Video purchase!
The Amiga Primer
Anyone with an Amiga -
whether a new owner or an
experienced user — will
find this easy-to-1ollow video
invaluable. Applicable to all Amiga models,
The Amiga Primer presents System 2.0 and
AmigaVision^" the Amiga Workbench, the CLl
peripherals, and utilities in an entertaining
tormat with vibrant graphics and upbeat music
There's no easier way lo master your Amiga!
#TMAP 90 minutes ^n^ tJH-^^
FREE!
Psygnosis
Lemmings™
Game
Demo Disk
with your order
Newtek's Video Toaster
Tbe Video Toaster'" from
NewTek is hailed as the
world's first video computer
card enabling broadcast-qual
ity production on desktop.
Whether you are considering
the purchase of a Toaster™
or are just curious about
all the excitement, the
Video Toaster'" video tape
provides In-depth Informa-
tion such as:
• Installing the Toaster'" in the Amiga 2000
• adding and testing other essential equipment
• selecting source material and processirvg
speed
• manipulation of many digital video effects
including flips, tumbles, mirrors, spins, splits
and titles
• producing 3-D animations
■ painting on video images
See for yourself what the amazing Toastef"
can do! -.^^^
#TMVT 45 minutes )^f^ t]%*iS
Hot Rod Your Amiga
Learn how to get maximum
power from your Amiga. Get
valuable advice on how to
expand memory internally
and externally; select and
install hard drives,
memory boards and
J accelerators; back-up
^^^^ software and utilities;
_^^fc^P^Y^^ RAM and drive space
' ^^^ VX^J^ differences; and other
■^^)Ji|^^^^ useful tips. Hot Rod
'' W Your Amiga also
f covers the revolutionary
Video Toaster'" and other high-end
peripherals such as DCTV. Soup up your
Amiga now!
#TMHR 45 minutes
>K!t^/''-^sr
NEW!^
Long
Awaited
Volume
Animation Video
Volume II
In response to the clamor for
another Amiga animation video-
tape, the AmigaWorld editors
have created Animation Video
Volume II. After sifting through
hundreds of contest submissions and"'
viewing countless hours of animation clips,
the result is a showcase of scintillating anima-
tions, technical brilliance and imaginative
plots. You'll be thoroughly entertained as you
absorb new techniques and ideas. Whether
you just brought your Amiga home from the
store or have created your own animations
before, you'll want to add Animation Volume II
to your Amiga video collection!
#TMAV2 90 minutes S?^ ^/'?.^5^
Desktop Video, Volume I
Whether for home or studio use,
Desktop Video shows you how
to utilize your Amiga in conjunc-
tion with a video camera to
create professional-quality productions with live
video and animation techniques. Learn how to
select a genlock; build a desktop video system;
choose and use a video camera; create scripts,
storyboards and titles. Plus tips on editing,
adding sound, special effects, and much more.
A must for any video enthusiast!
#TMDV 84 minutes SSg^ ^ZH.'K
Call Toll-free 1-800-343-0728
The AmipaWorld Catalog • PO Box 802 • 80 Elm Street • Peterborough, NH 03458
THE AMIGAWORLD CATALOG
The Musical Amiga
With detailed insight from some
of the best-l<nown Amiga musi-
cians, The Musical Amiga
teacfies you how to create both simple
tunes and complex musical compositions.
Sessions on MIDI systems include sequencing
editing and synthesizing. Learn the techniques
used in digital sound sampling, sound manipu-
lation ancJ creation o( unique sound effects.
Accompanied by an entirely Amiga-produced
soundtrack, this dynamic video is sure to
eniighien you with the remarkable musical
polenlial of your Amigal
#TMMA 60 minutes J^S^ "^2^.95^
Animation Video, Volume I
A best-selling video, containing commercially
broadcast and award-winning animation art,
this video will fascinate, entertain and inspire
you as it demonstrates the amazing capabilities
of Amiga animation. Each of the many anima-
tions is accompanied by unique music and
sound effects, and is prefaced by the artist's
name and a listing of all the animation products
used. Experiment and explore the endless
possibilities yourselfl
#TMAV 48 minutes ^Mfc§l ^/V.^"
AMIGA BOOKS
Amiga Graphics
Amiga Graphics is all you need to explore the
extraordinary graphics capabilities of your
sophisticated Amiga. Learn the pros and cons
of the most popular paint programs. Get three
intensive sessions on fonts, clip art and digitiz-
ing, as well as in-depth coverage on the
elements of design and style, Amiga Graphics
also illustrates interlace functions, when Hold
And Modify (HAM) should be used, and covers
smearing, washing, tinting and perspective. An
invaluable tool for any artist!
#TMAG 54 minutes ^SM^.T^^.^S'
Amiga Is a isgistered trademark of Commodore Business
Machines, Inc.
Video Toaster Is a reglsteree) trad9mar1< o! NewTek, Inc.
New Edition!
AmigaWorld Official AmigaDOS 2
Companion
by Bob Ryan
^, Harness the power
of the new
..! AmigaDOS 2!
"^ The Amiga
Companion is
; back — In a
^ revised and
- expanded
edition for AmigaDOS 2.
Ifs your expert guide to the new DOS, filled
with hundreds of instructions, tips & tech-
niques not found In any other book.
Covers:
• The Amiga OS, Including Workbench, Shell
&ARexx
■ The Workbench GUI
• Workbench menus and tools
• The 1 3 Preference Editors
• The Extras 2 disk
■ AmigaDOS — handling disks, flies &
devices
■ Configuring AmigaDOS
• Manipulating files with Copy, Delete,
MakeDIr, Rename
• AmigaDOS command scripts and shortcuts
• The ARexx macro language and a fully
annotated program to customize
• Plus over 100 screen shots, command
references, a valuable glossary, and an
error code summary for solving problems
more easilyl
#1-878058-09-6 41 6 pages $24.95
AmigaWorld Official AmigaVision
fiandbook
by Louis Wallace
Express your aeattvity on the Amiga — with
this complete guide to the new AmigaVision!
TJie only authoritative guide to the hottest
program for your Amiga. Written in an easy-
to-follow style and heavily Illustrated, with
over 150 screen shots, this book provides a
step-by-step primer for mastering
AmigaVision.
Special Features:
"What exactly multimedia is, the art of author-
ing, the basic menus, common requestors,
and program editing Information
• Control commands covering: Interrupts,
database icons, wait icons, audiovisual
icons, and module Icons
> In-depth editors, tools, and programming
information
■ Valuable appendices filled with advice on
the best hardware and software products
for AmigaVision, and a special guide to
version 1.7.
#1-878058-15-0 353 pages $24.95
Call Toil-free 1-800-343-0728
The AmigaWorld Catalog • PO Box 802 • 80 Elm Street • Peterborough, NH 03458
TJ891
Get Noticed
Convince the press to spread the word
on your product for you.
By Brian Sarrazin
YOUR PRODUCT IS going to change the face of Amiga
computing. If people knew about the technological wonder
you created, they would beat a path to your door offering
gobs of cash. The problem is they either do not know about
your product or know about it but do not fully understand
what it can do for them. So how do you get the word out?
Blanketing the market with ads and trade show demos will
get you name recognition, but at a hefty price. If your bud-
get is small, you are better off talking someone into doing the
shouting for you for free. You need to convince the press to
cover your product. Before you start dialing the phone, how-
ever, take these hard-learned lessons to heart.
SPEAK THE LANGUAGE
First, consider the perspective of your target audience and
the context within which the message is delivered. You must
understand how to speak the language of your listener to be
understood. Communicating in a manner that is consistent
with your audience's thinking style will also help.
With these thoughts in mind, you are ready to tailor your
message to the experts in the press who can cover your prod-
uct — the editors. Look at the mastheads of your favorite Ami-
ga magazines. The editors listed are the people who will help
you, if you help them first.
Editors pride themselves on objectively surveying the mar-
ket and delivering important information to their readers. If
editors feel that many people will benefit from your product,
then it has a high level of newsworthiness. Make no mistake,
a high level of newsworthiness is like having money in the
bank. To convince them, you must tell the editors the benefits
your product can deliver. To do this, study each magazine
covering the Amiga market (and perhaps a few that cover the
vertical market your product falls into), create and send the
proper communication devices, and follow up appropriately.
Start by analyzing the magazines to garner an idea of the
type of things the editors feel are important. It will also help
to understand the editorial style. Read the feature articles in
recent issues with an eye to grammar as well as to content.
Look at the products reviewed. Scrutinize the helpful hints
section for ideas on the type of issues the readers are
wrestling with and, consequently, the concerns of the editors.
To further help you understand the editorial perspectives,
request a media kit from each magazine. Inside the kit
you'll find an editorial calendar outlining the magazine's
planned emphasis for the coming months. Look for areas
that your product may fall into and time your correspon-
dence accordingly.
Learn the responsibilities and style of every editor on the
56 August/September 1991
masthead. Each will have a different reason for being inter-
ested in your product. The new products editor hopes to cov-
er all that's new. The review editor hopes to coordinate and
deliver objective summaries of key products' effectiveness.
The features editor is interested in how products fit into key
areas of functionality. Once you understand their interests
and concerns, you are ready to contact the editors.
Editors prefer to be contacted first with printed matter, a
press release and a cover letter. If you tailor your material to
each one's style and perspective, you help them determine
more quickly whether your product warrants coverage. Once
decided, an editor may be interested in spending some time
uncovering the details via the phone.
PUT rr ON PAPER
The press release is by far your most important tool to
catch the editor's attention. As you only have about two sec-
onds to do so, use your time wisely. Objecti\'ely report the
facts and answer the five basic questions — who, -ivhat, when,
where, and why — in as few words as possible. Tlie pyramid
approach is best: First supply the bare facts, then present the
facts with some elaboration, and finally give the facts with
significant elaboration. The most difficult part will be keep-
ing your statements objective. You know how tremendous
your product is, but you must contain your enthusiasm.
There is no room for subjective opinion in a press release.
Structure the page for a quick read. The first line should tell
the editor who to contact for more information. Underneath
the name, list the phone number only. Next, you should in-
dicate when the information may be released to the public,
usually "FOR IMMEDIATE RELEASE." After this comes the
headline, which must get attention. Indicate the most note-
worthy aspect of your product here with a minimum of
words. Adjective count: zero. Write that your company an-
nounces (or begins shipping) Product A and then state your
most important reason for creating it. Double-space the re-
maining copy and leave generous margins to give the editor
plenty of room to make notes.
Write the press release to mirror the target magazine's
style, so the editor merely has to cut and polish it to suit the
magazine's new products or news column. This helps the
editor and it helps you communicate more directly to poten-
tial customers who read the magazine. Your goal is to write
a press release that the editor does not have to change at all.
Keep in mind, however, editors often will not print what
they cannot confirm. If your product is not in the editor's
hands, do not be surprised if your confident "WonderDrive
is three times faster than existing drives" is changed to
"WonderDrive claims to be three times faster than existing
drives."
Keep the first paragraph compact. Start by stating where
the newsworthy event took place: where you began shipping
your product or made an announcement. Was it at company
headquarters, a trade show, a special press conference? Next
indicate the date of the event. You have now covered the
who, what, when, and where. Next, expand by more fully de-
scribing the what. For example:
New York City, New York, September 1, 1990 — Big Time
Publications today announced a new magazine to be called
Laimt Care lotinial. Starting with its first issue in early 1991,
Lawn Care journal will cover items of interest to professional
groundskeepers and wiU be edited by Jean Hobbs.
In the second paragraph introduce the why. Why will the
Amiga community benefit from your product? Because the
answers lean toward the subjective inherently, a quote does
the job best. For example, just fill in the blanks of the sample
template below;
"We feel there is a tremendous need for
based
on what we hear during on-line roundtable discussions. For
this reason, we have created the first for the
Amiga computer. It will revolutionize the way people
," said , president of .
The remaining paragraphs should go into increasingly
greater detail and should include another quote. Don't get car-
ried away; a press release should rarely be greater than 300
words. The above two examples total nearly 100 words already.
The cover letter lets you get into the why in detail and is
essentially your opportunity to persuade the editor that your
product is very newsworthy. Tailor each letter to the needs
of the editor receiving it. Do not print 20 cover letters and 20
press releases and send them out to "Editor" or "Dear Sir."
This is sure to alienate as it indicates a low level of concern
for the editors' individual interests. A half-hearted effort will
get you the results it deserves.
Remember: The less hype the better. Start your letter with
a brief, 25-word statement of why you created your product.
You should be able to use the first quote from your press re-
lease. If you can't, rethink your press release. In the second
paragraph weave key features into your discussion of how
you solve the users' needs. This shows that you put serious
thought into the features you included, and maybe the ones
you left out as well.
ILLUSTRATED BY LAURA STEARNS JOHNSON
If your product is shipping, send it with the press release
and letter. This gives your statements more weight, as the ed-
itors can see your product is real. If the product is still in de-
velopment, send review copies as soon as it is ready. Do not
fall prey to the "If they want to look at it, they can buy it" phi-
losophy. If you do, your product will be relegated to obscu-
rity, Remeniber, the press is helping you. They communicate
with a very large group of Amiga users for you. Give away
review copies liberally. In the case of hardware, simply loan-
ing a unit is acceptable. You are still better off, however, send-
ing a copy for keeps. That way the editors will have your
product on hand if they schedule a related article a few
months after it was released. Don't send a crippled version.
Tlie people of the press are professionals. You insult their in-
tegrity by sending a disabled version.
The last item to slip into the press package is a picture of
the product, the packaging, or a sample screen. Look through
the magazine to see which is preferred. The picture should
be in slide format and on a disk as an IFF file.
FEEL FREE TO CALL
Follow-up phone calls are your next step. Again, vary the
timing and purpose based on each editor's needs.
New products editors move at a quick pace. They have too
much to report and not nearly enough time. Show you un-
derstand their time constraints. Make sure the significance of
your product is evident from reading the press release alone.
Limit your follow-up call to introducing yourself, ensuring
that the package was received, and inviting the editor to call
you back if needed. The timing here is critical. The sooner you i
The AW Tech Journal 57
Organize and Protect
your copies of
The AmigaWorld
TECH JOURNAL
i here's an easy way to keep
copies of your best source
of advanced technical
infomation readily available
for future reference.
Designed exclusively for
The AmigaWorld Tech Journal,
these custom made 2-inch
vinyl titled binders are sized
to hold a year of issues.
Jf'^g'ht^j
^^JqC|n[ai:
Each binder is oniy $9,95
(Add $1 for postage & handling. Outside U.S., add $2.50 per binder.]
For Immediate service cati toll free
1-800-343-0728
(in New Hampshire, cali 1-603-924-0100)
Enclosed is $_
for
binders.
ZIP
TJB591
~ Check/money order enciosed
Charge my
_; MasterCard n Visa C American Express D Discover
The AmigaWorld Tech Journal Binder
80 Elm Street
Peterborough, NH 03458
Get Noticed
call, the better, but do not call until you are sure your pack-
age is on the editor's desk. Sending the material via overnight
or second-day express is very effective.
Review editors look for in-depth information. Do not at-
tempt to provide it all in the press release, but make sure to
explain why your product advances the state of Amiga com-
puting, not merely why you made it. Follovv-up is very im-
portant. Remember that a fair review could be the best thing
that ever happened to your product. Your objective should
be to clarif)' the reasoning behind your product and to de-
termine where to send review copies. You will probably be
asked for two copies. One will be for the editorial office and
one for the person writing the review. (Do not ask for the re-
viewer's name; this is not professional.) Allow a couple of
weeks to pass before calling. Realize that there are too many
products vying for too little space and scheduling is a key
aspect of the review editor's job. A two-week delay between
receipt of the package and your call reflects your under-
standing of this. When asked for a review copy, send it ex-
press and call to ensure it arrived on schedule. Always no-
tify the review editor of any updates that might affect a
potential review or one in progress.
Features editors look for the most comprehensive infor-
mation and work the furthest in advance. Consult your edi-
torial schedule and look at the feature articles or issue themes
conung up. Find one that most closely fits your product and
explicitly mention the relationship in your cover letter. Indi-
cate precisely how your product fits into the area to be dis-
cussed. (Keep the magazine's lead time in mind, however; ed-
itors often are working on issues four or more months ahead
of the cover date.) A couple weeks after you send your pack-
age, call to ensure it arrived and offer to send anything else
the editor might need for upcoming articles. Watch the edi-
torial calendar and call again about the time the features ed-
itor plans the issue for which your product is appropriate. As
for the review editor, alert the features editor to updates to
the product that might affect coverage.
DON'T TAKE IT PERSONALLY
If you encounter editorial resistance to covering your prod-
uct, do not become defensive or hostile. These people know
more about the needs of their readership than you do. Your
job is to make the benefits of your product clear. If you have
done so and the editor decides that it is not worth covering,
you have just received a very valuable lesson. Find out why
they feel as they do. Perhaps they could direct you to a more
appropriate magazine to cover your product.
If the editors decide to mention your product, find out ex-
actly when the issue it is appearing in will be on the shelves.
Time your discussions with other key community players
(such as software resellers or publishers) with the release of
the magazine; it will add credibility to your product.
The importance of communication cannot be overempha-
sized. No one will be interested in your product if they do not
understand what it can do for them, if you think in terms of
helping the experts who can help you, you will earn the press
coverage your product deserves. The result will be throngs
of Amiga owners beating a path to your door offering gobs
of cash. ■
Brian Sarrazin is the Western Regional Manager for RGB Coin-
pufer & Video. Write to him cjo The AmigaWorld Tech Journal,
80 Elm St., Peterborough, NH 03458.
58 August/September 1991
^
Start-up Messages
Pay attention, maybe your Amiga is trying
to tell you something.
By David W. Martin
AS YOU NO doubt have noticed, when you boot under OS
1 .3 your screen flashes a series of colors. Aside from simply
loading the Workbench, your Amiga goes through a series of
initialization and test procedures when you turn the power
on or reboot. Not simply reassurance that "something is hap-
pening," the colors provide information on the results of
these tests. Watch the flashes: If you learn how to interpret
the colors, they can provide early warning signs to system
failures.
Each time you boot, your system conducts the verification
and initialization steps below:
1. Clear hardware data registers (custom chips, and so on)
of old data.
2. Disable interrupts and DMA during testing procedure.
3. Clear the screen display.
4. Test the hardware and check that the CPU is working.
5. Change screen color to show the results.
6. Perform a checksum test on ROM.
7. Change screen color to show results.
8. Begin the system startup begins.
9. Test the SCOOOO RAM and place SYSBASE
information there.
1 0. Conduct a test on chip RAM.
11. Change screen color to show results.
12. Test to check if software is coming v«thout errors,
13. Change screen color to show results.
14. Prepare chip RAM for data.
15. Link Amiga libraries.
16. Test for and additional memory expansion
and link it if found.
17. Restore interrupts and DMA.
18. Begin execuHon of a default start-up task.
19. Test for usage of a 68010, 68020, 68030, or 68881/2.
20. Test for exception (or processor) error.
21. If an exception occurs, reset the system.
A healthy system flashes the following sequence on screen
as the tests proceed:
Dark gray
Light gray
White
The first color indicates that the CPU test was passed and
the 680x0 is up and running fine. The second reassures you that
the software is corning in without problems. Finally, the white
flash signals that the system passed all initialization tests.
Upon encountering trouble, the system changes the screen
to one of the danger sign colors and halts all activity. A red
screen indicates a ROM checksum error occurred. Green de-
notes an error in chip RAM, while blue tells you one of the
custom chips has a problem. A yellow screen reports that the
680x0 found an error before the system's error- trapping soft-
ware (guru) was started. While you probably will never re-
ceive an error message, the most common is the green screen.
Many early Amiga 500s had loose Agnus chips, which caused
chip RAM errors. Gently, but firmly, pushing in the chip usu-
ally solved the problem.
A SYSTEM ALL ITS OWN
While the CPU is the most obvious about its activities, your
keyboard undertakes its own start-up sequence when you
power up or reboot. A self-contained system, an Amiga key-
board houses a CPU, 2K of ROM, 64 bytes of RAM, four
eight-bit I/O ports, and a timer, all of which are monitored
by error checking and initialization software. When you boot
your machine, the keyboard routines:
1. Check ROM with a ROM checksum test.
2. Check RAM with a RAM test.
3. Check the timer to ensure it is functioning.
4. Syncfu-onize the keyboard with the computer.
To alert you to any errors it encounters, the keyboard
blinks the light on the Caps Lock key. The number of blinks
identifies the error. The blink code is:
One Keyboard ROM checksum failed.
Two Keyboard RAM test failed.
Three Keyboard watchdog timer test failed.
Four A short exists between two row lines or one of the
seven special keys (currently not implemented).
Chances are you will never encounter an error flash or
blink. If your system does start acting strangely, however,
pay close attention at startup for these warning signs. While
they will not tell you the whole problem, they will point you
and your repair technician in the right direction, saving him
time and you money. ■
David W. Martin is the nuthor for the 1581 DOS Reference
Guide and a frequent contribufer to Amiga publications. Write to
him c/o The Amiga World Tech Journal, 80 Ehn St., Peterbor-
ough, NH 03458, or contact him ou PeopleLink (davidm), Compu-
Serve (72510,3232), or Usenet (davidm@liackercorp.com).
TIte AW Tech journal 59
Reviews
From p. 37
event MouseXC) but everit_menu-
subitemO. There was no index. The
documentation appears to have been
set up for on-line browsing rather than
paging through a printed copy; the
files are organized one per routine in
object-grouped subdirectories, which is
only good if you have hard-disk space
to spare and a multiwindow editor.
I tried the package with SAS/C 5.10
and Aztec C 5.0a, by adapting some
existing code. The sources with
amigaview.h included compiled ac-
ceptably, the objects linked, and the
executables ran. I didn't notice any
obnoxious slowing, and the gadgets
and menus worked just fine. The add-
on size of the library was not out of
line with what I expected.
Using AmeegaView routines re-
duced typing time, and to some extent
simplified the edit-compile-test cycle.
Don't expect a no-brain solution,
however; you can't use the routines
without knowing what Intuition does
and what its data structures specify.
New programmers will still have to
learn window and screen setup and
Intuition/ AmigaDOS message pro-
cessing. AmeegaView merely makes it
easier to deal with the nitty-gritty of
typing in and compiling all those
specifications. It will make your pro-
grams a little more readable and a
little easier to test. It won't make
Intuition any less complex.
AmeegaView is a good package, but
a real manual and better naming con-
ventions would make it a better one.
AmeegaView
ACDA Corp.
220 Belle Meade Ave.
Setauket, NY 11733
516/985-1700
$79.95
No special requirements.
MINIX 1.5
A little Unix for the Amiga.
By Stephen R. Fietrowicz
A UNIX-COMPATIBLE operaHng
system, MlNlX (which stands for
Mini-Unix) was written by Andrew
Tanenbaum, a professor at Vrije
Universiteit in Amsterdam, The
Netherlands, as a teaching tool for his
classes. The Amiga version of MINIX
offers a relatively inexpensive way to
learn how an operating system, and
Unix in particular, works.
Amiga MINIX is actually a port of a
port. The original IBM PC version of
MINIX was ported to the Atari ST,
and that version was ported to the
Amiga by Raymond Michels and
Steven Reiz. Interesringly enough,
under MINIX, the Amiga and Atari ST
can exchange and run binaries with-
out modification.
You'll find most of what you'd ex-
pect on a regular Unix Version 7 sys-
tem in MINIX and a good working
knowledge of Unix and it's utilities is
essential. The package includes nearly
all of the standard Unix utilifies (over
175), a Bourne shell work-alike, a K&R-
compatible C compiler, five editors,
and over 200 library procedures. Addi-
tionally, because the utilities and the
operating system code were written
from scratch, MINIX can be sold with-
out having to deal with licensing re-
strictions for the source code. In addi-
tion, the package includes complete
source for everything except the C
compiler and one of the text editors.
MINIX will run on a one-megabyte
Amiga 500 or an A2000, and it will
also recognize expansion RAM and
extra floppy drives. MINIX does not,
however, support the 68020, 68030, or,
in the release version, hard drives.
However, there is a beta version of
MINIX that supports the A590 con-
troller for the Amiga 500. If you have
access to Internet, you can download
the beta version that supports the
A590 from star.cs.vu.nl at address
192.31.231.42. (It's probably also avail-
able at the sources mentioned later in
this review.) Even if you don't have an
A590 controller, I encourage you to
find the new binary of MINIX. It
seems to make the floppy disks work
much more reliably.
SETUP
MINIX comes on nine disks — one
{your boot disk) in AmigaEXDS format
and the rest in IBM format. You can
use a commercial or PD IBM disk-
copying program, or use the MINIX
"diskcopy" command after booting
MINIX to make backups. If you use the
latter method, you must first format
the backup disks using the transfer
utility before booting MINIX. Format a
few extra disks, because the Amiga
version of MINIX doesn't have a for-
matting utility. If one of the disks is
bad, you'll have to reboot AmigaDOS
to reformat another. I usually keep a
few extra disks formatted to avoid
having to reboot. MINIX seems to be
very particular about its floppy disks,
and it rejected many that 1 tried.
When the system boots, it loads the
root partition completely into RAM.
The other partitions, such as /usr, can
then be mounted on one of the exter-
nal floppy drives. You can also in-
crease the root partition's size to allow
more binaries to be loaded into RAM
and significantly increase the speed at
which programs will load and run.
UTILITIES
MINIX comes writh many utilities
(disk utilities, text formatting utilities,
communication programs, and more),
and most work well. For example, I
used kermit to test the serial device. 1
was able to dial up a local Unix system
and transfer files back to my own
system without any problems.
A few other utilities, such as the vi
editor, didn't perform as well on the
first try. The /usr disk as distributed
■was not set up correctly; a directory
that vi uses to store its temporary files
was missing. After I created the direc-
tory, all went smoothly.
I also had a problem trying to ex-
tract some of the source-file archives
while attempting to recompile the
entire operating system. All of the
source comes in compressed archives.
Decompressing the archives seemed
to work correctly, but when I tried to
extract the source from the resulting
files, I didn't get very far before re-
cei\'ing an error message. I tried at
least five times with the file-system
source archive, and each time 1 re-
ceived a different error message. Be-
cause I was unable to overcome that
problem, 1 was unable to recompile
the OS as 1 had hoped. I should also
note that not all archives exhibited this
problem. I was able to extract some of
the source from different archives.
The need for hard-disk support was
very evident when I started using the
compiler. It expects to run out of the
/usr directory, and because the com-
piler and the utilities on the /usr disk
won't all fit on one disk, I had to rear-
range things a bit to get a working
compiler disk. Luckily, most of the
compiler disk is already put together,
so it isn't that difficult. Compiling
60 AugusllSqjtember 1991
Reviews
programs on floppies is pretty slow,
though. A simple four-line "hello,
world" program took 1 minute and 45
seconds to compile to executable.
THE MANUAL
Amiga MINIX users will find the
manual a bit disappointing, because it
contains very little Amiga-specific
information. Amiga owners are almost
always referred back to the instruc-
tions for the Atari ST. To be fair, most
of the information supplied will work
for the Amiga, but there are a few
things in the manual that are just plain
wrong. For example, the information
on creating a larger root partition is
incorrect for the Amiga. When I fol-
lowed the Atari ST instructions (as
advised), I was unable to get MINIX
to complete loading the RAM disk
and then ask for the /usr partition.
Everything hung up after loading the
RAM disk. After a little experiment-
ing, I found that using a different
device name for the floppy disk I was
creating worked. The manual recom-
mends running a system verification
test when you boot MINIX for the first
time. I tried to run the test, but it
wasn't even included on the disk!
The rest of the manual looked fine.
It contains a complete explanation for
each of the commands, along with
examples. There are also extended
pages for more complicated utilities
such as kermit and the text editors.
Plus, the manual has a brief, two-page
explanation of the 49 system calls that
MINIX supports and the source listing
for most of the OS.
SUPPORT
You can get your MINIX questions
answered from a variety of sources.
The best is the comp.os.minix news-
group on USENET. You can speak
directly with Andrew Tanenbaum, as
weU as Steven Reiz. The group is in
the process of reorganization, so by the
dme you read this, there will be a
separate group for binary and source
distributions. If you don't have access
to USENET, you can participate in
MINIX discussions on the Mars Hotel
BBS, 301 /277-9408. If you live outside
the US, call NLMUG-ONLINE in
Holland at (02522) 18363.
For more in-depth information about
MINIX, you can pick up the book
Operating Systems: Design and Implemen-
tation by Andrew Tanenbaum, from
Prentice-Hall. Although it refers to an
earlier version of MINIX, most of the
concepts still apply. If you plan to do
any serious work with MINIX, I recom-
mend you get the book.
FINAL THOUGHTS
I have mixed emotions about
MINIX. Tlie package has a lot of
promise, but it falls short in some
areas. For example, such features as
networking and hard-drive support
that are supported on other platforms
are not available for the Amiga. I hope
this is rectified in the next version. If
you don't have access to any of the
support sites listed above, you'll have
a hard time with MINIX and I suggest
waiting for the next release. ■
MINIX 1.5
Microservice Customer Service
Simon &: Schuster
200 Old Tappan Rd,
Old Tappan, NJ 07675
800/624-0023
$169
One megabyte required.
Graphics Handler
From p. 16
functions in your input-event loop lets you properly handle
special GadTools operations. These functions also return use-
ful information in the Code field of the IntuiMessage. For ex-
ample, the actual position of a scroller or slider is provided in
tliis field, as well as the color selected from a Palette gadget.
When you finish your gadget list, you can dispose of the
entire affair with a single call to FreeGList( ), passing the orig-
inal gadget list pointer provided to CreateContextO.
GadTools are not only simple to create and use, they are
also easy to enhance and modify. Because of the amount of in-
formation on GadTools gadgets alone, I did not go into Gad-
Tool's new menu facility (which greatly simpUftes menu cre-
ation, see David Joiner's article, "Menus for a New
Generation," p. 4, April /May '91) and some of the other fea-
tures and factors of using GadTools. If you wish to dig deep-
er into the mechanics of GadTools, I suggest you study your
2.0 GadTools header files.
It is important to keep in mind that GadTools is not com-
patible with OS 1 .3, so take care when using this powerful li-
brary. Ideally, you should provide a backup arrangement us-
ing standard gadgets. If you cannot do that, request 2.0
explicitly, and then exit gracefully if it is not available. If you
intend to sell your software commercially or distribute it
widely in the Amiga market, you would do well to consider
1.3 compatibility a must — at least for now. ■
Paul Millerhas been a dmeloper since 1985. Write to him c/o The
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH
03458, or via Internet (pmilier ©vttcf.cc.vt.edu).
Become a part of the
AmigaWorld
Programming Team
We're looking for quality programs to support
the growth of the AmigaWorld product line
and we need your help.
We offer competitive payment
and an opportunity for fame.
■GAMES -ANIMATION -30 ■UTILITIES
-APPLICATIONS -CLIP ART
■ AMIGAVISION APPLICATIONS
■OTHER STAND-ALONE APPLICATIONS
Send your submissions or contact us for guidelines!
Amiga Product Submissions
Mare-Anne Jarvela
(603) 924-0100
80 Elm Street, Peterborough, NH 034S8
The AWTech journal 61
step Up To The Podium!
Adirdt it. You're an expert. You know how it works better than (almost) any-
one. When you write code, you play by all the rules, yet your programs consis-
tently out perform even those of the most wild-eyed ROM-jumping hacker. It's
been obvious to you for some time that you should sit down at the keyboard, fibre
up your trusty text editor, and write an article explaining exactly how and why it
should be done your way.
If the above description seems to fit you to a T, perhaps we should be talking.
The AmigaWorld Tech Journal is looking for technical writers who have expertise in
one or more areas and have a burning desire to share that information with the
Amiga technical community. We need experts in all aspects of programming the
Amiga, from operating systems to graphics to the Exec. You can write in any lan-
guage you like— C, Assembly, Modula n, or BASIC. Best of aU, you can include as
much source code as you need, because all source and executable is supplied to
the reader on disk. We also need hardware maestro's who can explain— in thor-
ough detail— the inner workings of such complex components as the Amiga's
chip set, expansion bus, and video slot. Don't forget algorithms either, we'll help
you pass on your theories and discoveries.
The AmigaWorld Tech Journal offers you an unparaUed opportunity to reach the
Amiga's technical community with your ideas and code and to be paid for your
efforts as well. So, whatever your "it" is that you want to write about. The Tech
Journal is the place to publish it.
We encourage the curious to write for a complete set of authors guidelines and
welcome the eager to send hardcopies of their completed articles or one-page
proposals outlining the article and any accompanying code. Contact us at:
The AmigaWorld Tech Journal
80 Elm St.
Peterborough, NH 03458
603/924-0100, ext. 118
62 August/ Sqjtember 199]
Ray Tracing
From p. 30
owchkO (in math.h), which creates a ray extending from the
intersection point to the light source. It then checks to see if
any polygons intersect the ray. (See Figure 12.)
If it finds an interesection, the function returns true indi-
cating that the light is blocked and the point is in shadow. If
the point is in shadow, the color is set to a very dark brown,
otherwise it is set to a much lighter shade.
If a ground hit is not detected but polygon hits were, we
call the shadepointO function (in math.h) to shade the inter-
section point. ShadepointO uses the vector dot-product op-
eration to calculate the cosine of the angle between the in-
coming light ray and the intersected polygon's surface
normal. The size of the angle determines the brightness of the
surface at that point. In addition, the function checks if the
point is in shadow. If so, the intensity of the surface point is
reduced to account for the lack of light.
If we do not find a ground or polygon hit, the sky is visible
for the pixel. In this case, tracer calls shadeskyO (in math.h) to
calculate a sky color. For effect, this routine shades the sky as
though it has a different color at the zenith than at the horizon.
Again using the dot product, the funcHon calculates the cosine
of the angle between the ray and the ground's normal. The
greater the angle, the more the horizon color is used, and the
smaller the angle, the more the zenith color is used. A simple
linear interpolation mixes the two colors.
After the color for the current pixel is calculated, the pro-
gram calls storeRGBO to store the color's RGB values in the
global RGB buffers. To finish the tracing of the pixel, its color
on the screen is turned to gray. The loop then continues to pro-
cess the remaining pixels in the same manner.
As you can see, we have to deal with pixels only on an in-
dividual basis. This means that the entire ray-tracing process
breaks down to the question, "What does this pixel's ray
see?" It is the sophistication with which you answer this ques-
tion that determines the quality of the resulting image.
When all the pixels have been traced and the tracing is
complete, the program calls the last function, writeRGBO
(located in write.c), and passes it the object's file name in the
same manner as for the loadobjectO function. WriteRGBO
writes each RGB buffer as a separate file. Each file is giv-
en the same name as the object, with a .red, .grn, or .blu
suffix appended to it. These RGB files contain the final
image and can be viewed using View (in the Wagner
drawer) or The Art Department (TAD) from ASDG. In
TAD, separate red, green, and blue RGB files are referred
to as the Sculpt format.
LOOKING GOOD
Although our trip was a simple one, you can make ray
tracing more sophisticated in many ways. Tlie best example
is the shading function. A more powerful shading function
would take into account variable surface attributes and tex-
tures. This, by itself, would create much more realistic im-
ages. In addition, you could add reflection and transparen-
cy/refraction to increase the quality even more. With a little
ambihon, you can turn out beautiful ray-traced images with
your own program. ■
Brian Wagner, oiw of the founding members of Cryogenic Soft-
ware, is fJic developer of 3-D Professional. Contact him cjo The
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH
0345S, or via PeopleLink (CRYO) or CompuServe (72137,573).
Become a part
of the
AmigaWorld
Programming
Team
We're looking for quality
programs to support the growth
of the AmigaWorld
product line and we need
your help.
We offer competitive payment
and an opportunity for fame.
GAMES "ANIMATION
■ 3D ■ UTILITIES
■ CLIP ART
■ AMIGAVISION
APPLICATIONS
OTHER STAND-ALONE
APPLICATIONS
Send your submissions
or contact us for
guidelines:
Amiga Product Submissions
Mare-Anne Jarvela
(603) 924-0100
80 Elm Street, Peterborough,
NH 03458
The AW Tech journal 63
LETTERS
Flames, suggestions, and cheers from readers.
HLL 'EM UP
I liked your first issue, but 1 have a
few suggestions for improving the disk.
1 . Do not have icons that open to
show an empty window,
2. Put a ReadMe file in each directory.
3. Include a contents file (a la Fred
Fish) with page references to make
locating the associated article easier.
These minor changes would make
things much better, espedally if the
disk gets separated from the magazine.
Urban Ludwig
Laurel, Maryland
As you can see from this issue's disk
(and the June/ July issue's), we have made
some changes. Drawers in the Articles
director]/ are noio labeled with the au-
thor's name and the page number of the
related article for quicker reference be-
tween the text and code. Every drawer
also lias a ReadMe file (with an icon),
listing the files the directory contains and
other pertinent notes. The neio ReadMe
file in the root directory holds Inte-break-
ing additions and corrections that didn't
make it into print. Finally, we moved
Lharc into the main directory for easier
access. If you can think of any other im-
provements, let us know.
SHARED STRIPS
In "Menus for a New Generation"
(p. 4, April/May '91), David Joiner
implies that having windows share
menu strips is a quick way to get a
guru. While this is generally true,
there are special cases where it is false,
such as when the hvo windows are
also sharing ports. While making this
work right is tricky, it is a worthwhile
thing to know how to do.
Mike Meyer
Palo Alto, California
You can have two windows sharing
the same menu strip, at least under 1.3
and below. I am providing two short
programs as documentation for my
assertion- (See the Letters drawer on
the accompanying disk.) The first,
MenuShare, opens three windows on a
custom screen and attaches the same
menu strip to each. The second, Menu-
List, displays all screens, windows,
and attached menu strips known to
Intuition. Tlie address of the Menu-
Strip structure is displayed in hexadec-
imal format. 1 suggest you open a
couple of disks and other \\indows on
the Workbench screen. You wU find
that Intuition itself uses the same
MenuStrip for each of its windows!
Fred Scheifele
Hamilton, New Jersey
I stand corrected. Menus can be shared
if all the ivindows are managed by the
same task and have the same UserPort.
David Joiner
BETTER DOCS, PLEASE
The lack of proper system docu-
mentation has been a great contributer
to the failure of the Amiga to catch on.
The Amiga is a difficult machine on
which to program — not because of the
language of choice (C), but because
system documentation is inadequate.
With an operating system that is
ROM-based, changes in the OS invali-
date much of the existing documenta-
tion, and new documentation lags too
far behind the OS releases.
Too much of the "how-to" docu-
mentation for the Amiga consists of
poorly translated European texts,
often containing Httle content. Even
the "real reference materials" fail to
present all necessary information
(such as library references, precedents
of function calls, addressing modes,
and so on), or present the information
in an unorganized, hard-to-follow
fashion. 1 know of many potential
developers who simply gave up trying
to write software for this system.
For the machine to succeed, more
users are needed. To get more users,
more quality software is needed. To
get more quality software, more de-
velopers are needed. To get more
developers, we must make it worth
their time and effort to pursue an idea
and turn it into an application.
Thomas R. Clark
Utiion City, California
LIBRARY LAMENTS
1 hoped the article "Shared Libraries
for the Lazy" (p. 30, April/May '91)
would help me with my shared li-
brary project. Several times I tried
unsuccessfully to build a shared li-
brary include file with Manx-style
pragma statements as shown in the
comment section of the example pro-
gram Simple.c. If 1 modified the .fd file
to show which register to use I always
got an error message and no pragma
statements. Only if the function defini-
tion had no arguments did LibTool
write a pragma statment.
Alfred Steele
San Antonio, Texas
The proper procedure for using LibTool
with register args and Manx 5.0 is as
follows: First, alter the .fd file to include
the desired register placement. For Sim-
ple.c, for example, the functions would
look like:
Add2Numbers(num1 ,num2)(d0,d1 )
Sub2Numbers{num1,num2HdO,d1)
Mu1t2Numbers(num1 ,num2)(d0,d1 )
Invoke LibTool as noted in the starting
comment section of Simple.c. Remember to
include the pragmas in the header file for
both the library and the application, other-
wise, the compiler won't know lohere you
want the args placed.
Jim Fiore
WHAT'S ON YOUR MIND?
We're ready to listen to your sugges-
tions for the magazine or Amiga develop-
ers, complaints, or cries for help ivith
technical issues. Just write to Letters to the
Editor, The Amiga World Tech Journal,
80 Elm St., Peterborough, NH 03458, or
speak your mind in The Amiga World
Tech journal conference (A W.Tech-
Journal) on BiX, Letters and messages
may be edited for space and clarity, m
64 AugustlSeptember 1991
issues, plus 6 invaluable disks)
Charter Subscription to The AmigaWorld Tech Journal
for ihe special price of S59.95. That's a savings of
S35.75 off the single copy price. If at any time I'm not
satisfied wiih The AmigaWorld Tech Journal, I'm
entitled to receive a full refund — no questions asked.
Ciniili ind Meikico S14 95 Foreign Suffice S8J,95. Fortign Aiimiil SV9.<)5
Payment required m L' S. funds drai*T an L S hank Aviilible Mari;h !5.
-Zip-
n Check/Money ontcr enclosed TS41!
Charge my; □ MMIcrcard DAM EX □ Visa Q Discover
Accoui^t# Exp ,
Or call 800-343-0728 ^ 603-924-01 00 for immediate service.
6 Bl-MONTHLY ISSUKS 6 INVALUABLE DISKS
BUSINESS REPLY MAIL
FIRST-CLASS MAIL PERMIT #73 PETERBOROUGH. NH
POSTAGE WILL BE PAID BY ADDRESSEE
The Amiga World Tech Journal
P.O. Box 802
Peterborough, NH 03458-9971
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES
,m,.II..I..I,I,I,I„M,I„I.ImI.„Ii..II,I,.II
The AmigaWorld
TECH TOURNAD
Q ■ CO ! Enter my one-year
(6 bi-monthly issues, plus 6 invaluable
disks} Charter Subscription to The
AmigaWorld Tech Journal for ttie
special price of $59.95. Tticrt's a
savings of $35.75 off thie single copy
price, if at any time I'm not satisfied
with The AmigaWorld Tech Journol,
I'm entitled to receive a full refund
— no questions as!<ed.
Name
Address_
City
State
J Cfieck /Money oniei enclosed
Chorgemy: □ MasterCard 'jVlsa
Account*/
JtP.
TL41I
U Amex Q Discover
Exp
Stgnolure
Canooa and Metico %7A 95 Fofeign Surtoco SW.flS. Foieign Aiimofl SW 95,
Payment (ei^uued in u.S. Funds Orotvn on u.S BonJi. AvaitaWe Moicr^ 1 5.
Or call 800-343-0728 ff 603-924-0100 for immediate service.
BUSINESS REPLY MAIL
FIRST-CLASS MAIL PERMIT NO. 73 PETERBOROUGH, NH
POSTAGE WILL BE PAID BY ADDRESSEE
AmlgaWorld Tech Journal
P.O. Box 802
Peterborough, NH 03458-9971
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED
STATES
I ll..l..l.l.l.l..l.l.l..l.l..l.nl.Mll.l..ll
A source of technical
information for the serious
Amiga professional.
Iniroducing The AmigaWorld Tbch Journal,
the new source lo turn to for the advanced
technical information you crave.
Whether you're a programmer or a
developer of software or hardware,
you simply can't find a more useful
publication than this. Each big, bi-
monthly issue is packed with fresh,
authoritative strategies and advice
to help you fuel the power of your
computing.
Trying to get better results from
your BASIC compiler? Looking for
good Public Domain programming
tools on the networks and buHetin
boards? Like to keep current on
Commodore's new standards? Want
to dig deeper into your operating
system and even write your own
lioraries? Then The AmigaWorld Tech
Journal is for you!
Our authors are programmers themselves, sea-
soned professionals who rank among the Amiga
communily's foremost experts. You'll benefit
from their knowledge and msigh! on C, BASIC,
Assembly, Modula-2, ARexx and the operating
system— in addition to advanced video, MIDI,
speech and lots more.
Sure, other programming publications may in-
clude some technical information, but none
devote every single page to heavyweight tech-
niques, hard-core tutorials, invaluable reviews,
listings and utilities as we do.
Every issue includes
a valuable companion dislil
And only T/ie AmigaWorld Tech Journal boasts
of a technical advisory board comprised of in-
dustry peers. Indeed, our articles undergo a
scrupulous editing and screening process. So you
can rest assured our contents are not only
accurate, but completely up-to-date as well.
Plus! Each issue comes with a valuable compan-
ion disk, including executable code, source code
Tlic AmtqaWorld
TECH JOURNAL
and the required libraries for all our program
examples— plus the recommended PD utilities,
demos of new commercial tools and other helpful
surprises. These disks will save you the time,
money and hassle of downloading PD utilities,
typing in exhaustive listings, tracking down errors
or making phone calls to on-line networks.
In every issue of The AmigaWorld Tbch Journal,
you'll find. . .
• Practical hardware and software reviews, in-
eluding detailed comparisons, benchmark
results and specs
• Step-by-step, high-end tutorials on such topics
as porting your work to 2.0, debugging, using
SMPTE time code, etc.
• The latest in graphics programming, featuring
algorithms and techniques for texture mapping,
hidden-line removal and more
• TNT (tips, news and tools|, a column covering
commercial software, books and talk on the
networks
• Programming utilities froin PD disks, bulletin
board systems and networks
• Wise buys in new products— from language
system upgrades to accelerator boards to edit-
ing systems and more.
The fact is, there's no other publication like The
AmigaWorld Tkcb Journal available. It's all the
tips and techniques you need. All in one single
source. So subscribe now and get the most out of
your Amiga programming. Get six fact -filled
issues. And six jam-packed disks. All at special
Charter savings. Call 1-800-343-0728 or complete
and return the savings form below-todayf
To order, use
this handy
savings form.
Ur
Charter Savings Form
E \o c I ^"'^'' ^y ons-year (6 issues, plm 6 invaluable
ICO • disks) Charter Subscriplion to The AmigaWoM
Tech /oriraai for just $59.95. Thai's a speda! savings of $35.75 off
tlie singie-copy price. If at any time I m not satisfied with Vie
AmigaWorld Tscli loumal, I'm entitled to receive a full refund-
no questions asked!
Name
AiJdress
City State Zip
n Check or money order enclosed. HCIiaijemy:
UMasterCaid ZJVisa ~l Discover D American Eitpress
Account Ko. ._ Exp. Dale
Signature —
Satisfaction
Guaranteed!
Or your money back!
Canada and 4Merico, $7495.
Foreign surface, S84.97,
Foreign airmail, S99.95.
Rayment required in U.S.
funds drawn on U.S. bank.
Complete and mail to:
The AmigaWorld
Tecbjournal
P.O. Box 802, 80 Elm Street
PelerboiDugh.NH 03458
TJ891
For faster
service, call
toll-free
1800-3430728.
"The Toaster pro\ ides a wider r:in.s;e
ot fiiiK'tions Ifiiin :iiiy ciinihitiiUion ot
soliilioris found on (Mats or I'Os) —
and a( a f'rartioii of the cost. It could
do for personal and corporate \ideo-
lape publisliitis; what (Jutenherii did for
the printed w(»rd'.'
- Conilmh'r C.iinviits
■■(Icniiniodores Amii;:i conipoler
plalforni may have foinid iheappMeation
it's heen lookinj; for witli the
Video Toaster!'
-liijhWbyld
"provides broadcast quality desktop
video at a heretofore unheard-of price!'
- 'li'k'riskm HmidatsI
"poised to j*»in the camcorder and ^(]R
as a home video appliance!'
- \'k/c(ti^niphy
"took the National Association of
Broadcasters tonveiiticvn hy storm "
-I'.k'droiiH Media
■se\eral networks plan to use the low
cost system , , . lelevision w ill neier
be the same "
■ 'IV Tcchiuil(ti[v
"they could have doubled the price and
still had to beat off potential customers!'
- liivaclccLst Haniiniiv
"One of the stars of NAB"
'Tvk'i'isiim Ihtwr
"NewTek was approached separately
at (loiiidex by Apple and IHM. both
offerinj; New fek whatever it cost to do
a version of the I'oaster for their
respecli\'e s\stems!'
-iHjuWofkl
"Both the talk and the toast of the
video world, its impact will he roughly
that of fire to food, the wlieel to
transportatitu), and the priiitin;; press
to [Hiblishin^!'
- Chris! hill Scicmv ,\Uiiiik)r
"it represents a si)ini(icant new direction
III home video's future . . . oulperforms
SlOd.OOO dijiiial effects iinils!"
- Video Miiiimlin'
"the Mdeo 'I'oaster promises lo toast
dozens of hiyh-end \ideo t;ear makers
Into bankruptcv ... it provides about
SlUO.tKK) worth of power!'
-John Dronik. l'CMai>iizi)w
"there may be loLs of people who wilt
buy the Amii^a just so they can use
the loiLster!'
-AmigaWorkI
"Hill f>ales. the Microsoft Moi;ul, will
be .netting his \ery own Mdeo Toaster!'
-liiJhWorkl
'a sinniflcant price-perf(M-maiice
breakthrough "
- Vidivaniphy
"the first breakthroiisjh product in
the Am iya video realm"
-.iriM'o
"This is .uoinj; to sell a lol of
AiTiijjas ... it will help drive the .Vniiga
market as nothiii!^ else has!'
- . iiijh
"will forever change the way in which
we communicate!'
- Camamter
"Tiie Video Toa.stcr will open up new
markets for the .\mi);a "
OmiliiitcrGmphics World
"Something's biirnini». and its not the
Toast. It's the ears of network executives!'
-Miniiaifiolis Star Trihunv
N=wl=K
INCORPORATED
l-«00 8 45-S934
"Makes a personal computer act (ust
like a HolMvood production studio "
•USA lodiiy
"The equivalent of a S6(>,()()1)
lelevision studio"
-Self York limes
"Coolest video/i;raphic product
of the vear"
-Ifyk'
"a crusade to brinj; liifjli quality video
functions to the mass market"
-AV Video
"The highlight of the recent Comde.\
trade show "
-John Dnmik in Mini 'scr
"Ironicidly, our favorite hardware
product of MacWorld Rxpo "
-Mad^eek
"The Toaster creates desktop v idco the
way Apple Computer and Aldus Corp.
created deskto]) publishing"
- Ij)s Ai/gck's 'limes
"The hit of Comdex was neither PC
nor Mac related. It was the \idco ToiLstcr"
- WdsbiiigtOH I'ost
"as capable its gear normally
costing S6(»,0<)() "
-Business Week
"special effects magic"
-Success
"u.sed by everybody from the guy who's
entering .America's Funniest Home
Videos all the wa\ up to MT\ "
■Post
"The Mdeo Toaster is the world's first
deskt<)p television studio!"
- Comjniley & Business
'li'cl.mokigy
"the same functionality as professional
V idco editing and switching equipment
thai costs from 10 lo SO times the price!"
-l'C,M(ig(i:ine
"made the biggest splash at this year's
.NAB . . . the product the Amiga has
been wailing for!'
- Videogmphy
Live Music
Archive
Librivox
Free Audio
Metropolitan Museum
Cleveland
Museum of Art
Internet
Arcade
Console Living Room
Open Library
American
Libraries
TV News
Understanding
9/11